Friday, July 29, 2011

MSCRM 2011 Developer Toolkit Walkthrough

As you may have noticed that MSCRM team has released a new version of SDK (v5.0.5) today. The SDK includes a full functioning Developer Toolkit, which, IMHO, marks a significant milestone in CRM development practice. For the first time, the CRM development community has a first-class solution template within Visual Studio. Using the solution template, we can create, develop and deploy CRM Plug-ins, custom workflows, and web resources without having to leave the Visual Studio environment. The toolkit is designed to be a set of integrated tools within Visual Studio which help improve development productivity for Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online.

This blog post will walk you through some typical CRM development scenarios, which I hope can help you become familiar with the new toolkit, so that you can take full advantage of it.

Prerequisites

The Developer Toolkit requires the following components

Installation of the Toolkit

The installation package of the toolkit can be found in the SDK download package at SDK\Tools\DeveloperToolkit. Double click "CrmDeveloperTools_Installer.msi" to install the toolkit.
Note: If you happen to have a previous version of the toolkit installed, you need to uninstall it first before installing the new version.

Note: The Developer Toolkit does not support Visual Basic .NET. If you happen to be a VB.NET developer, you will have to think about switching to C#. I doubt there is any plan to release VB.NET version of the toolkit anytime soon.

Create a New CRM Solution

To create a new CRM solution using the solution template provided by the toolkit, please follow the procedures below.
  1. Within Visual Studio 2010, click File –> New –> Project menu.
  2. In the "New Project" window, navigate to "Dynamics CRM" under "Visual C#", and choose "New Visual Studio Solution Template for Dynamics CRM 2011", and enter a solution name before click "OK" button. 
    0 - New CRM Solution Template
  3. You will be prompted to enter CRM server connection information as shown below. Provide the name of your CRM server, and click "Connect" button. 
    1 - Enter CRM Discovery Server Name and Connect
  4. Then you will need to provide authentication information in order to connect to the CRM discovery server. After you have done so, you can click "Log on" button. 
    2 - Enter Authentication Details to Log on
  5. You will now be asked to choose a CRM organization and a solution that you would like to work on. After you have provided all information required, you may click "OK" button now. 
    3 - Pick Organization and Solution Name
  6. By default, the CRM solution template will create a Silverlight project, and a companion web project for you. Enter the Silverlight web project name and click "OK" button to continue. 
    4 - Create New Silverlight Application by Specifying the Application Name
    Note: You may not necessarily need Silverlight project in your CRM solution, but you should simply provide a Silverlight web project name in order to make the solution template wizard happy so that it can finish its own job. You can later delete the Silverlight projects if you don't actually need them.

    Note:
    If you don't currently have Silverlight Developer toolkit installed on your computer, you will be prompted the following window. 
    4 - Silverlight Developer runtime required for CRM Developer Toolkit
  7. If everything goes fine, you will see a screen of Visual Studio as shown below. Notice that the wizard has created a Visual Studio solution which consists of a few projects, including:
    Project Role in Solution
    CrmPackage The manifest project that that contains all assets to be deployed to Microsoft Dynamics CRM, combined with their deployment settings
    Note: You should never delete this project in your CRM solution.
    Plugins The Plugins project contains a base class named Plugin. All plug-in classes generated through the Create Plug-in option of the CRM Explorer will derive from this class. This class simplifies some of the plumbing code that's required by many plug-ins.
    SilverlightApplication A sample Silverlight project that can be used as the starting point to develop your Silverlight web resource.
    SilverlightApplication.Web A companion web project that host the above Silverlight project, and can be used to test the Silverlight project.
    Workflow The Workflow project provides support for implementing custom workflow activities to be used for your on-premises Microsoft Dynamics CRM instance.
    Note: Microsoft Dynamics CRM Online does not currently support Custom workflow libraries, so you may delete this project if you are working for Microsoft Dynamics CRM Online.
    5 - Generated New CRM Solution
    Note: In the above screen, you can see a new window called "CRM Explorer", which I will explain in details next.
  8. Once the CRM solution has been created, the first thing you should do is to sign both your Plugins and Workflow projects with a strong name key file. You may sign your projects with a new key file or an existing one if you already have. 
    6 - Sign CRM Plug-in and Workflow Projects with Strong Name File

Use of "CRM Explorer" Window

CRM Explorer is a very useful window that's designed to help you navigate through any customizable components on your CRM server in an organized fashion.
6 - CRM Explorer
As shown above, CRM Explorer presents you a tree window that you can use mouse click to navigate through the solution components that you are interested in. The following is a screen that shows how it looks like when it has been expanded (I truncated some entities in the screen to make it concise).
8 - Expanded CRM Explorer
In addition to the navigation features, CRM Explorer allows you to open the CRM solution component in Visual Studio browser when you double click the item. The following screen shows how it looks like when you double click a CRM entity (Account entity in this case) in the explorer.
11 - Open CRM Customization Page in Visual Studio
Another great feature offered by CRM Explorer is, you can perform certain tasks by using context menu commands when you right-click on a specific item. The following is a list of some typical scenarios that you would use the right click commands in CRM Explorer.
  1. Generate CRM Service Proxy Classes
    Context Entities
    Command Generate Wrapper
    Description Executes CrmSvcUtil.exe to generate the strongly typed proxy classes. If you only have one plug-in project, this class will automatically be added to this project; otherwise, the Generate Entity Wrappers dialog box will allow you to choose which Project to create the classes in.
    Steps
    • Right click on "Entities" node in CRM Explorer window
      13 - Generate CRM Service Proxy Classes in CRM Explorer
    • Choose which project that you want the proxy classes to reside in
      14 - Choose which Project the CRM Service Proxy Classes Reside In
    • Wait until it finishes generating the proxy classes, this could take a few minutes depending on the complexity of your customizations and your hardware configuration.
      15 - Generating CRM Service Proxy Classes
    • The following is a screen of the generated code. 
      16 - Generated CRM Service Proxy Classes
  2. Create Plugin for CRM entities
    Context Entities –> Specific Entity
    Command Create Plugin
    Description Opens the Create Plug-in dialog with the Primary Entity set to the selected entity.
    Steps
    • Right click a specific entity that you would like to create a plug-in, and choose "Create Plug-in" from the command menu
       16 - Generate CRM Plug-in in CRM Explorer
    • Specify the details of the CRM Plugin 
      17 - Create CRM Plug-in
    • Once the plugin code has been generated, you can see that the new plugin class inherits from the base Plugin class
      18 - Generated CRM Plug-in
  3. Add Web Resource items from CRM Server to the packaging project
    Context Web Resources  or Web Resources -> Web Resource Type   or
    Web Resources -> Web Resource Type –> Specific Web Resource
    Command Add to packaging project
    Description Add selected web resources from the CRM organization to the CrmPackage project.
    Steps
    • Right click specific web resource item, a web resource type, or the Web Resources folder, and choose "Add to packaging project" from the command menu 
      9 - Add Web Resources to CRM packaging project 
    • You should be able to see the selected web resources added to your CrmPackage project, from there you can work with the CRM Web Resources just like any other source code files.  
      10 - Added Web Resources 
  4. Add, Edit, Delete Plugin  
    Context Plug-in Assemblies -> Specific Assembly   or
    Plug-in Assemblies -> Specific Assembly -> Specific Plugin
    Command Add Plugin Edit Plugin Delete Plugin
    Description Add, edit or delete CRM plugins.
    21 - Add plugin in CRM Explorer
    22 - Edit, delete plugin in CRM Explorer
  5. Add, Edit, Delete Plugin Steps  
    Context Plug-in Assemblies -> Specific Assembly -> Specific Plugin   or
    Plug-in Assemblies -> Specific Assembly -> Specific Plugin -> Specific Step
    Command
    Add Step
    Edit Step
    Delete Step
    Description Add, edit or delete CRM plugin steps.
    23 - Edit plugin step in CRM Explorer

Use of "CrmPackage" Project in "Solution Explorer" Window

CrmPackage project is a specially engineered Visual Studio project template designed to manage all CRM solution components within a single place.
  1. Manage CRM Web Resource Metadata Attributes CRM Web Resource has certain metadata attributes associated, which dictate how the web resource items can be accessed and managed in CRM system. To change a web resource item's metadata attributes, you can click any particular web resource item in Solution Explorer window to open its Properties window, where you can change or update any properties as necessary. 
    19 - Manage Web Resource Properties
  2. Manage Silverlight Web Resource Metadata Attributes Silverlight web resource is a special web resource type which is added to CrmPackage project through project reference. In order to change Silverlight web resource's metadata attributes, you need to expand CrmPackage project's References node, and click on the particular reference item, so that you can change or update any metadata attributes in Properties window as needed. 
    20 - Manage Silverlight Web Resource Properties
Note: The above two approaches are particularly useful if you have any source code files that are not currently managed by CRM Server yet, but you want to publish them to CRM Server, in which case, you can use Visual Studio's Add Existing Items command to add them to CrmPackage project, then you would provide necessary metadata attributes before you can actually deploy them to CRM server.

Publish Changes to CRM Server

After you have done all the good hard work on your CRM solution, you are ready to publish your changes back to CRM Server. The CRM Solution template has made this significantly easy, you can right-click the CrmPackage project, and choose "Deploy" from the command menu, all the changes will be published to CRM Server after all referenced projects have been successfully compiled.
24 - Deploy CrmPackage
Note: You need to make sure that you have signed all plugin and workflow projects in order for Visual Studio to be able to publish them to CRM Server.

I have tried to cover some most common development scenarios using the toolkit in this blog post, but I am sure that there are many other things that I haven't covered, which you can explorer by reading the user guide document that you can find from the SDK.

Note that the toolkit is currently a beta version. I have encountered a few minor issues when using it. Overall, it's a great productivity tool for CRM development. Great job by the CRM team.

Please let me know if there are any errors or typos in this post.

Hope this helps. Cheers!

55 comments:

  1. Great post Daniel, I think this post is the best documentation currently available for this tool. Thanks.

    ReplyDelete
  2. Excellent post! Just one thing, it seems to me that some text appears to be trimmed, it would be great if you could fix it. Thank you!

    ReplyDelete
  3. Thanks Paul and Nicolás.

    Nicolás, you may try to use a system that has higher screen resolution (1280 x 800 should do). Some of the screen shots were a little too large, they have stretched the screen a bit, I guess that's the reason that you are seeing the trimmed text. Please let me know if that's not the case.

    Cheers,
    Daniel

    ReplyDelete
  4. Hi again, thank you, that worked for me. I'm a contributor to a MS CRM spanish blog, and I've posted a translation of this post here: http://elblogdedynamicscrm.com/post/2011/08/02/Tutorial-del-nuevo-Kit-de-Desarrollador-para-Microsoft-Dynamics-CRM-2011.aspx. Again, thank you very much.

    ReplyDelete
  5. Nicolás, thanks for your effort of translating the post.

    ReplyDelete
  6. Hi Daniel,

    Nice post, the only problem I saw is that when you generate the wrapper, the OrganizationServiceContext is not created. I would usually use it for performing Linq queries against the AccountSet, ContactSet, etc... Is there a setting for this ?

    ReplyDelete
  7. Hi Mihai,

    I think that's an important missing feature of the tool. I have just submitted a request at Microsoft connect site. You may go add vote to this request so that it can be considered in future SDK releases.

    Thanks,
    Daniel

    ReplyDelete
  8. This comment has been removed by the author.

    ReplyDelete
  9. This is just a quick update. I have just added two more feature requests for the toolkit including the capability to support integrated authentication, and the ability to switch target server and CRM organization, among many other issues that I have previously reported while I was writing this blog post. Please help vote those issues.

    Thanks,
    Daniel

    ReplyDelete
  10. Awesome post, thanks Daniel!

    ReplyDelete
  11. Great post Daniel! This definitely helped me in my pursuit on attaining more knowledge on CRM Solution.

    ReplyDelete
  12. This is great information. Thanks Daniel!

    ReplyDelete
  13. Excellent post. Thanks for going through the main parts of the toolkit

    ReplyDelete
  14. Great post.

    The CRM Development kit is a great step forward by Microsoft, it makes development a lot easier

    ReplyDelete
  15. Thanks guys for all the positive feedback. @metaphorix, I am completely with you about the toolkit.

    Cheers,
    Daniel

    ReplyDelete
  16. Hi Daniel,

    First I apologize for my English ...

    I would like to thank you for the post, really its content was very important to us.

    I am a developer Brasiliero which also has a blog, I just did a post that quotes yours. Even I have published the post, would like your permission. Do not copy anything explicitly than did but follow the same line of reasoning, I think the most important case is the translation into Portuguese.

    See the post:

    http://tiagomcardoso.wordpress.com/2012/01/02/crm-2011-plugin-crm-online/

    I await the answer.

    Regards,

    ReplyDelete
  17. @tiagomcardoso, it is not a problem at all. It's actually the intention to spread the word about how the toolkit can help improve development productivity.

    Thanks for the effort.

    Cheers,
    Daniel Cai

    ReplyDelete
  18. Thank you Daniel, we continue the fight!

    ReplyDelete
  19. Hi Daniel,

    Congratulations for this thorough step by step guide.

    However, I'm encountering an issue while doing the connection setup.
    After I select my organization in the drop down list, the available solutions are not loaded. Clicking on [Log On] displays an error: Value cannot be null; Parameter name: source.

    This happens only on 1 PC while the exact same steps work without any issues on another PC.

    Do you have any idea what might cause this ?
    Thanks.

    ReplyDelete
    Replies
    1. Great post Daniel, I think this post is the best documentation currently available for this tool. Thanks.






      -------------------------------------
      cheap nba jerseys

      Delete
  20. @hdany, I am not sure about this error, and I have not run into the same problem so far. What I would do in this case is to delete the .suo file and try the same procedure again. If it doesn't help, I would uninstall and re-install the toolkit.

    ReplyDelete
  21. Thanks for the suggestions. I tried both approaches, unfortunately, with no luck.

    ReplyDelete
  22. Hello daniel. Nice to meet you I have a problem in step 5, in the Plug-in Assemblies shows nothing. I hope your help. thanks

    ReplyDelete
  23. @Veronica, nice to meet you too. If you haven't created any plug-in in CRM yet, it will not show anything, that's expected.

    Please let me know if that's not the case.

    ReplyDelete
    Replies
    1. Hello Daniel....

      I dont create plug in crm, but i solved the error!!...

      Now i have other problem..How can i the part entity below:

      "" +
      "" +
      "" +

      How do I get the values ​​of accountprimarycontactidcontactcontactid for entity link??
      I dont know how building the block ...I have 2 entity (relation n-n), ContratDetail and new_equipment....Pleaseeeeeeeee Helpmeeeeeeeeeeeee

      Delete
    2. @Veronica, your question didn't come through the blogger commenting system. Apparently some information is missing. I would recommend posting your question on CRM development forum if you run into any technical challenges. There are many talented folks there who can offer assistance.

      Delete
  24. I dont know how building the block from fetch

    ReplyDelete
    Replies
    1. If you are referring to FetchXml, you can try to use CRM advanced find to build a view, and then use the Download Fetch XML button to save the FetchXml to a local file. Not sure if that's what you are trying to achieve.

      Delete
  25. Hello every one

    I'm .net developer and i have a Dynamics CRM 2011 online version. When i Tried to create a visual studio 2010 crm solution with the sdk toolkit and i'm filling the crm server connection dialog, when i choose the Organization name, the drop down list of solutions stay blocked and i canot choose the solution wich i want to connect.

    What i have to do to choose the solutions in the dropdown list?

    The previous version works ok.



    Thanks a lot

    ReplyDelete
    Replies
    1. @herculigan, I have not run into this problem. This could be a bug of the tool, if it happens. You might want to post the problem to Microsoft connect site at http://connect.microsoft.com/dynamicssuggestions

      Delete
  26. Hi Daniel,

    Thanks for this excellent post!
    Well, I am facing issues while adding second step to the plugin. CRM explorer is allowing me to add a step but I am not able to debug the plugin with second step. The reason being, the plugin constructor is holding information only for the first step and nothing about the second step. Because of which, I am unable to debug the plugin.

    Could you please update me what's wrong?

    Thanks,
    Abhi

    ReplyDelete
    Replies
    1. @rocks, not sure if I misread anything, I don't believe this should happen. The toolkit won't affect Visual Studio's debugging capability.

      Delete
    2. We have the same problem. Adding successive steps does not update the ctor of the plugin. It does not add the event registration, which kind of defeats the point of having a toolkit.

      Delete
    3. ...NB, this is the VS2k12 version

      Delete
  27. This is a wonderful and clean post... well done.

    ReplyDelete
  28. Hi I have tried all the steps but when I get to deploy i Get
    Error 1 Error connecting to CRM Server. The server was unable to process the request due to an internal error. For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs. D:\Program Files (x86)\MSBuild\Microsoft\CRM\Microsoft.CrmDeveloperTools.CrmClient.targets

    ReplyDelete
    Replies
    1. The error message is too generic to tell what the problem is. You might want to turn on CRM trace log to see what the problem is. I suspect it is a permission issue, make sure you have at least System Customizer role. But again, it might be something else, since the error message doesn't tell anything.

      Delete
  29. Hi,
    Regarding debugging plugin, i faced the same issue. But then i found that the assembly has been deployed by the toolkit in sandboxed mode.
    Right click the assembly and set the mode to isolated and check. i was able to debug.

    ReplyDelete
  30. It's an awesome article, congratulations Daniel. Unfortunately I'm experiencing the same problem Veronica17 had at January, 2012 6:17 AM for the Plugin in step 5, she said that resolved but didn't posted the solution, do you know something about it? Any tip or help is welcome, if you need any additional information from me please let me know.

    ReplyDelete
    Replies
    1. @Marcelo, you will only see plugin step if you have previously registered one.

      Delete
    2. in the step 4 which is "Add, Edit, Delete Plugin" I'm not seeing these two contexts menu items:
      - *XrmSolution.Plugins
      - *XrmSolution.Workflow

      All the other previous steps have been done correctly. Because every picture you posted of every single step is exactly the same we have, except for this one at the fourth step.

      We do have 5 plugins registered in CRM, but we used another tool for that (plugin registration tool).
      Can you help us telling us what we are missing?
      Thanks for your incredible post and help, we really appreciate that.

      Delete
    3. Hi Daniel,

      I resolved it. In order to make it appear, it is necessary to right click the CrmPackage and select Deploy.
      It will makes the created plugins to appear in the left side tree.

      Best Regards,

      Marcelo Calado

      Delete
    4. @Marcelo, sounds good, thanks for the update.

      Delete
  31. Awesome post daniel, but its getting error ,then i tried again it is working now, thank you.Here is more information on CRM ,check this .Microsoft Dynamics CRM

    ReplyDelete
  32. Great Post Daniel.
    However i created a plugin and deployed successfully.
    But then don't know what happened but its now getting errors like
    "Public Assembly must have public key and Plug-in assembly does not contain the required types"
    and
    "assembly content cannot be updated"

    How to overcome from these errors.
    First i have deleted this Visual studio solution and also deleted plugin assembly from crm.
    and then follow this steps to create new plugin.. but again i stuck at these 2 errors.

    Please help.

    ReplyDelete
    Replies
    1. @Milan, did you sign the assembly? This can be done through the project's Properties window where you can find a page called Signing, you can define how to sign the project there.

      Delete
    2. Yes Daniel .. I followed all the steps again.

      Delete
    3. Hi,
      I deleted ll and done again.
      And i got these error
      "Public Assembly must have public key".

      I stuck at this.
      What is the solution for this??

      Delete
    4. @Milan, this blog post was not originally developed in a step-by-step fashion, I just tried to highlight some key things when using the toolkit. So when you say you have followed all steps, I believe you are referring to the screenshots in which case, you could still miss something. I would once again check whether the project has been signed.

      Hope this helps.
      Daniel

      Delete
    5. Hi Daniel,
      I solved this issue.
      I should have to sign key for Workflow solution too.
      Thanks.

      Delete
    6. Hi Milan, that's good to know, thanks for the update. It is appreciated.

      Have a nice day!
      Daniel

      Delete
  33. A word of warning about the Developer Toolkit. I had a need to manage just my web resources with this tool. I created a solution as described, and then removed the Plugins and Workflows projects. I then proceeded to add JavaScript files to the CrmPackage project and use Deploy to publish the changes to CRM. This seemed to work at first, until I needed to update a JavaScript file and redeploy.
    After I redeploy, I found that the CRM Solution is has not had customizations published. As a result, none of the changes to the JavaScript files are have been applied to the CRM forms that use the JavaScript. This toolkit is therefore not of any use in this situation.
    It appears that, unless you have a plugin and/or workflow DLL in the visual studio solution, the customizations in the CRM solution are not published.
    I know that this seems like a somewhat poor use the Developer toolkit, and that there are better tools for doing this, I would think it should have worked.
    My motivation was that I had originally created the solution with workflows and plugins and the crmpackage. After many customizations, including 100 plugins and workflows, it was taking 5-15 minutes to deploy. Also, the deploy resulted in every single plugin and every single workflow being reregistered. For instances where I needed to make a small change to a single JavaScript file, it seemed like a risky and wasteful effort to redeploy the solution. So I broke my solution into 3 parts, one plugins, one workflows, and one for web resources. That's how I arrived at where this post begins. In the future, I will be moving the VS2012/13 and using the Web Resource Linker to manage javascript.

    ReplyDelete
    Replies
    1. @Larry, thanks for sharing your experience. I definitely agree with you about the development experience in terms of the deployment process. For the deployment issue, I previously raised it as a request on Connect (just realized that request has been there for almost three years now). It might help if you add one more vote to the suggestion.

      Thanks!

      Delete