Este artigo foi traduzido por máquina.
Silverlight
Aproveitando o poder da API do Dynamics CRM 4.0 do Silverlight 4
Mark Beckner
Cada vez mais, as empresas estão implementando soluções Microsoft Dynamics CRM 4.0 e encontrando necessários para construir aplicativos externos que podem se integrar com a API baseada em serviços da Web existente.
Criando aplicativos que podem interagir diretamente com o Microsoft Dynamics CRM 4.0 (CRM 4.0 daqui em diante, por questões de brevidade) pode provam um desafio do Silverlight, devido à natureza assíncrona de chamadas do Silverlight e a incapacidade de chamar Web CRM 4.0 serviços diretamente. Neste artigo, você obterá uma análise detalhada como construir um aplicativo do Silverlight que pode ler e gravar dados por meio da API de serviço da Web do CRM 4.0.
Visão geral da solução
4 Do Silverlight e CRM 4.0 são as duas tecnologias poderosas — mas não são mais facilmente integrada. Analisarei os detalhes por trás da criação dessa integração, explorando as comunicações assíncronas entre o Silverlight e a API do serviço da Web do CRM 4.0.
Em aplicativos do Silverlight não típico, uma chamada para um serviço da Web é síncrona — a chamada sai, e o aplicativo aguarda uma resposta seja recebida. Durante esse período, o usuário não poderá interagir com o aplicativo e deve aguardar a ida e volta completa concluir. Em um aplicativo assíncrono, como o Silverlight, a chamada para o serviço irá, mas o aplicativo continua a ser totalmente funcionais mesmo antes que a resposta é retornada. Isso cria uma experiência de usuário sofisticados e dinâmicos, mas ele impõe demandas maiores ao desenvolvedor.
Para entender como essa comunicação pode ocorrer, apresentarei várias partes de funcionalidade. Primeiro, examinarei como configurar um aplicativo do Silverlight e trabalhar durante as etapas necessárias para interagir com um serviço da Web que atuará como um wrapper para a API do CRM 4.0. Em seguida, vou pesquisar os detalhes de como trabalhar com a API do CRM 4.0 e como ler e gravar dados usando o wrapper de serviço da Web. Vou trabalhar com as principais entidades usuário do sistema no CRM 4.0 e também examinar trabalhando com entidades dinâmicas. Por fim, observarei como lidar com os conjuntos de resultados retornados para o Silverlight. No final, você poderá criar seus próprios integrações do Silverlight/CRM 4.0 com facilidade.
Criando o aplicativo do Silverlight 4
Há várias etapas funcionem por meio de para obter um aplicativo do Silverlight configurado para interagir com o CRM 4.0. Embora seja possível referenciar o CRM 4.0 SDK ou a API do serviço Web diretamente no projeto do Silverlight, a maioria das interfaces e métodos, na verdade, não pode ser chamada a partir do código. Para interagir com a API do CRM 4.0, um serviço da Web de wrapper deve ser criado. Este serviço da Web será intercambiar as chamadas entre o aplicativo do Silverlight e a API do CRM 4.0 em um formato que pode ser manipulado pelo Silverlight. O wrapper do serviço da Web pode ser adicionado diretamente para o aplicativo SilverlightCRMDemo.Web.
Inicie esse processo criando uma nova solução Silverlight Visual Studio 2010 chamado CRM40SilverlightDemo. Ao criar um aplicativo do Silverlight em Visual Studio, os dois projetos são sempre criados. Um é o principal aplicativo do Silverlight; o segundo é o ASP.NET que incorpora o aplicativo do Silverlight em uma página da Web. Essa página ASP.NET também ser base para o wrapper de serviço da Web que irão interagir com a API do CRM 4.0. O aplicativo do Silverlight fará referência a este serviço da Web por meio de uma referência de serviço.
Para criar o wrapper de serviço da Web, adicione um novo serviço Web do ASP.NET e chamá-la CrmServiceWrapper. Neste exemplo, você adicionará dois métodos da Web ao serviço — uma para pegar os dados do CRM e outra para postar dados do CRM. Figura 1 mostra que esses métodos de stubbed-out aparência agora. Uma vez, você obtém o aplicativo do Silverlight se comunicando com êxito este serviço wrapper, atualizará esses métodos para chamar a API de 4.0 CRM real.
Figura 1 os Stubs de método Web
public class CrmServiceWrapper : System.Web.Services.WebService
{
[WebMethod]
public string GetCRMData()
{
return "This is the stubbed return for retrieving";
}
[WebMethod]
public string PostCRMData()
{
return "This is the stubbed return for posting data";
}
}
Depois que o wrapper de serviço da Web foi adicionado à página ASP.NET Visual Basic, a maneira mais fácil para adicionar uma referência a ele partir do aplicativo do Silverlight é executá-lo no modo de depuração e a URL onde o depurador está executando o aplicativo de captura (você pode simplesmente pegar o URL na janela do navegador que surge). Uma vez capturados, você pode adicionar uma nova referência de serviço chamado CrmServiceReference para o aplicativo do Silverlight e colar essa URL. Todos os arquivos de configuração relacionados e código serão automaticamente corrigidos. Se você decidir não fazer isso, você terá que lidar com exceções de referência entre domínios — e muito mais a instalação para depurar com sucesso seu aplicativo.
Agora que a referência existir, a codificação real no aplicativo do Silverlight pode ocorrer. O código consiste em um manipulador de eventos para cada método da Web de fiação e criando dois métodos para manipular dados quando tem concluído as chamadas para esses métodos da Web. O código mostrado na a Figura 2 podem ser adicionados diretamente ao arquivo MainPage.xaml.cs no aplicativo do Silverlight. Executando isso fará com que ambos os métodos execute simultaneamente.
Figura 2 Adicionando código para MainPage.xaml.cs
using CRM40SilverlightDemo.CrmServiceReference;
public partial class MainPage : UserControl
{
public MainPage()
{
InitializeComponent();
// Call the GetCRMData Web method.
CrmServiceWrapperSoapClient proxyGet =
new CrmServiceWrapperSoapClient();
proxyGet.GetCRMDataCompleted +=
new EventHandler<GetCRMDataCompletedEventArgs>(proxy_GetCRMDataCompleted);
proxyGet.GetCRMDataAsync();
// Call the PostCRMData Web method.
CrmServiceWrapperSoapClient proxyPost = new CrmServiceWrapperSoapClient();
proxyPost.PostCRMDataCompleted +=
new EventHandler<PostCRMDataCompletedEventArgs>(proxy_PostCRMDataCompleted);
proxyPost.PostCRMDataAsync();
}
// Called asynchronously when the GetCRMData Web method returns data.
void proxy_GetCRMDataCompleted(object sender, GetCRMDataCompletedEventArgs e)
{
// Do something with the data returned.
string result = e.Result.ToString();
}
// Called asynchronously when the PostCRMData Web method returns data.
void proxy_PostCRMDataCompleted(object sender, PostCRMDataCompletedEventArgs e)
{
// Do something with the data returned.
string result = e.Result.ToString();
}
}
Quando você tiver validado que seu aplicativo do Silverlight está sendo executado sem erros e retornar os dados do serviço da Web, você pode ativar sua atenção para desenvolver as chamadas à API do CRM 4.0. Essas chamadas serão todos ser contidas os métodos de serviço Web wrapper GetCRMData e PostCRMData Web que já foram criados.
Interagindo com a API do CRM 4.0
Há dois principais serviços da Web disponíveis por meio de CRM 4.0: o CRMService e o MetadataService. Esses serviços da Web estão geralmente disponíveis para fazer referência a partir de qualquer projeto (mas, na verdade, não permitem a funcionalidade muito quando referenciado a partir de um aplicativo do Silverlight). A maneira mais comum e eficiente para trabalhar com a API está usando o SDK do Microsoft Dynamics CRM (disponível para download em bit.ly/6M3PvV). O SDK contém várias classes e métodos, e simplifica a comunicação entre.NET Framework e os serviços da Web do CRM 4.0. Nesta seção, você aprenderá como interagir com a API usando o SDK do wrapper de serviço do Web.
A primeira etapa é fazer referência às assemblies adequadas CRM SDK. No ASP.NET que abriga o wrapper de serviço da Web, adicione uma referência a dois assemblies do SDK: microsoft.crm.sdk.dll e microsoft.crm.sdktypeproxy.dll. Depois que eles foram mencionados, adicione as diretivas apropriadas na parte superior da página da CrmServiceWrapper.asmx da seguinte maneira:
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;
using Microsoft.Crm.Sdk.Query;
A próxima etapa é escrever código para instanciar um serviço CRM que permitirá que você se conectar a uma instância de CRM 4.0. Esse código será usado pelos métodos de GetCRMData e PostCRMData Web, portanto, ela residirá no seu próprio método. Esse método (mostrado na a Figura 3) requer dois campos de chave: o nome de organização da sua instância do CRM 4.0 e o URL do serviço principal CRM (localizado em /MSCRMServices/2007/crmservice.asmx). Observe que esses campos são melhor armazenados em um arquivo de configuração para modificação fácil após compilar o código.
Figura 3 O método GetCRMService
static public CrmService GetCRMService()
{
CrmService service = new CrmService();
CrmAuthenticationToken token =
new Microsoft.Crm.Sdk.CrmAuthenticationToken();
token.OrganizationName = "Contoso";
service.Url = "http://localhost:5555/MSCRMServices/2007/crmservice.asmx";
service.Credentials = System.Net.CredentialCache.DefaultCredentials;
service.CrmAuthenticationTokenValue = token;
return service;
}
Consultando dados do CRM
Você pode agora voltar sua atenção para consultar dados do CRM 4.0. É importante saber que existem dois tipos de entidades no CRM 4.0: principais entidades do sistema e entidades personalizadas. As entidades do sistema de núcleo podem ser seguidas com um pouco mais facilmente do que entidades personalizadas. Por padrão, todas as propriedades em entidades principais podem ser recuperadas através dos objetos com rigidez de tipos em C#. Entidades personalizadas são geralmente consultadas como entidades dinâmico, embora uma alternativa permite que eles sejam tratados como objetos com rigidez de tipos, também. Demonstrarei consultando dados com os dois tipos de entidades.
Um exemplo de consultar uma entidade do sistema principal — a entidade do usuário do sistema — é mostrado na a Figura 4. Esse código substitui o método da Web com o mesmo nome que estava oculto neste artigo. Esse novo código, quais consultas CRM 4.0 para todos os usuários do sistema, você verá várias coisas importantes. Primeiro, o tipo de objeto lidado com é "systemuser." Todas as entidades principais têm seus próprios tipos. Segundo, o resultado que está sendo retornado é uma representação de seqüência de caracteres de um documento XML.
Figura 4 consultando a entidade de usuário do sistema
[WebMethod]
public string GetCRMData()
{
// This will return all users in CRM in a single XML structure.
StringBuilder xml = new StringBuilder();
CrmService service = GetCRMService();
QueryExpression query = new QueryExpression();
query.EntityName = "systemuser";
query.ColumnSet = new AllColumns();
RetrieveMultipleRequest retrieve = new RetrieveMultipleRequest();
retrieve.Query = query;
retrieve.ReturnDynamicEntities = false;
RetrieveMultipleResponse retrieved =
(RetrieveMultipleResponse)service.Execute(retrieve);
xml.Append("<Users>");
for (int i = 0; i <
retrieved.BusinessEntityCollection.BusinessEntities.Count; i++)
{
systemuser user =
(systemuser)retrieved.BusinessEntityCollection.BusinessEntities[i];
// Create a string represenation to return to Silverlight app.
xml.Append("<User");
xml.Append(" FirstName ='" + user.firstname + "'");
xml.Append(" LastName = '" + user.lastname + "'");
xml.Append(" SystemUserId = '" + user.systemuserid.ToString() + "'");
xml.Append(" JobTitle = '" + user.jobtitle + "'");
xml.Append("/>");
}
xml.Append("</Users>");
return xml.ToString();
}
Você encontrará as opções para retornar dados para o Silverlight estão muito limitadas. Por exemplo, é possível retornar o BusinessEntityCollection para trabalhar, pois o Silverlight não é possível trabalhar diretamente com a API. Em segundo lugar, existem limitações com a passagem de XML para o Silverlight através de um serviço da Web. Portanto, no final, lidar com uma seqüência de caracteres simple provavelmente é sua melhor opção.
Consultar entidades personalizadas pode ser um pouco mais atrativo. A maneira mais comum para recuperar dados está usando uma entidade dinâmico para recuperar os resultados (um exemplo desse tipo de recuperação é mostrado na a Figura 5). O desafio dessa abordagem é lidar com atributos específicos nos filtros em expressões de consulta. Embora tudo o que for possível, IntelliSense não ajuda muito.
Recuperação da Figura 5 usando uma entidade dinâmica
public static DynamicEntity GetCRMEntity(
CrmService tmpService, String entityId, String entityName)
{
DynamicEntity crmEntity = null;
TargetRetrieveDynamic targetRetrieve = new TargetRetrieveDynamic();
// Set the properties of the target.
targetRetrieve.EntityName = entityName;
targetRetrieve.EntityId = new Guid(entityId);
// Create the request object.
RetrieveRequest retrieve = new RetrieveRequest();
// Set the properties of the request object.
retrieve.Target = targetRetrieve;
retrieve.ColumnSet = new AllColumns();
// Retrieve as a DynamicEntity.
retrieve.ReturnDynamicEntities = true;
// Execute the request.
RetrieveResponse retrieved = (RetrieveResponse)tmpService.Execute(retrieve);
// Extract the DynamicEntity from the request.
DynamicEntity entity = (DynamicEntity)retrieved.BusinessEntity;
crmEntity = entity;
return crmEntity;
}
Embora a abordagem de entidade dinâmico pode ser o mais comum, se você quiser ter total visibilidade da estrutura de sua entidade em Visual Studio e interagir com ele da mesma forma como uma entidade padrão, você pode criar um proxy para o CrmService. Em muitos casos, isso pode significativamente melhorar a experiência de desenvolvimento e fornecem mais flexibilidade em como o código pode ser escrito. Um proxy é nada mais do que uma C# arquivo gerado, com base na instância mais atual do WSDL CrmService. Para criar uma classe proxy para o serviço de CrmService principal, abra um prompt de comando Visual Studio e digite o seguinte, substituindo o URL no link apropriado para sua página de crmservice.asmx:
wsdl.exe /out:CrmSdk.cs /namespace:CRM40SilverlightDemo.WebReferences.CrmSdkhttp:
//localhost:5555/mscrmservices/2007/crmservice.asmx?wsdl
Este comando criará um arquivo C# chamado CrmSdk.cs no diretório em que você executou o WSDL. exe executável. Este arquivo deve ser adicionado ao seu projeto. Depois de adicionado, você pode trabalhar com qualquer entidade personalizada da mesma maneira como as entidades do sistema de núcleo. Se a entidade for alterado, basta atualizar seu arquivo de proxy C# e os novos atributos (ou outras modificações) estará disponíveis. Para fins do exercício atual, o arquivo C# proxy não será utilizado.
Atualização do CRM 4.0 dados
Depois de ter examinado como recuperar dados de CRM 4.0, agora você pode trabalhar por meio da data de lançamento. O código mostrado na a Figura 6 mostra como atualizar um registro de usuário do sistema. Ele requer que duas propriedades passadas em: o identificador exclusivo do registro do CRM 4.0 e o apelido. Para passar essas cadeias de caracteres, uma linha de código deve ser modificada no MainPage.xaml.cs, mostrado aqui:
proxyPost.PostCRMDataAsync("f04b02d9-ad5f-e011-a513-000c29330bd5","My Nickname");
Observe que a identificação é codificado na chamada para o método PostCRMData. Você vai querer inventar um mecanismo para a identificação de captura dinamicamente.
Figura 6 lançamento CRM 4.0 dados
[WebMethod]
public string PostCRMData(string userId, string nickname)
{
CrmService service = GetCRMService();
Key kid = new Key();
kid.Value = new Guid(userId);
systemuser entity = new systemuser();
entity.systemuserid = kid;
entity.
nickname = nickname;
service.Update(entity);
return "success";
}
Processando os resultados no Silverlight
Neste ponto, a solução deve ser recuperar e postar e receber dados de CRM 4.0. No entanto, nada está sendo feito com os resultados de seqüência de caracteres que são retornados para o Silverlight. O método GetCRMData está retornando uma seqüência de dados que contém um documento XML com todos os registros de usuário, mas que pode ser feito com isso? Dependendo do controle, talvez você possa vincular a XML diretamente, ou você talvez queira analisar o XML retornado e lidar com os elementos de dados individuais.
Um exemplo de loop pelos resultados retornados pode ser visto na a Figura 7. Este código mostra como carregar a seqüência de caracteres em um documento XML e percorrer todos os dados. Trabalhar com documentos XML no Silverlight, a funcionalidade mais versátil vem da classe XDocument. Isso pode ser acessado, adicionando uma referência a System.Xml.Linq em seu projeto do Silverlight.
Figura 7, trabalhando com XDocuments
void proxy_GetCRMDataCompleted(object sender, GetCRMDataCompletedEventArgs e)
{
XDocument xDoc = XDocument.Parse(e.Result);
string firstName;
string lastName;
string ID;
string title;
// Loop through the results.
foreach (XElement element in xDoc.Descendants("User"))
{
firstName = GetAttributeValue(element, "FirstName");
lastName = GetAttributeValue(element, "LastName");
ID = GetAttributeValue(element, "SystemUserId");
title = GetAttributeValue(element, "JobTitle");
}
}
private string GetAttributeValue(XElement element, string strAttributeName)
{
if (element.Attribute(strAttributeName) != null)
{
return element.Attribute(strAttributeName).Value;
}
return string.Empty;
}
Infinitas possibilidades
Há infinitas possibilidades ao integrar as duas tecnologias. Algumas das próximas etapas imediatas, que convém examinar são abordagens para manipuladores de exceção (Silverlight muitos controles ocultar exceções, portanto, você precisará lidar com isso em uma base caso-a-caso) e integração com vários controles. Independentemente da direção que você tomar, você já tem tudo o que precisa para criar soluções do Silverlight que ler e gravar dados com o CRM 4.0.
Mark Beckner é o fundador da Inotek Consulting Group LLC. Ele trabalha em toda a pilha da Microsoft, incluindo o BizTalk, SharePoint, Dynamics CRM e gerais.Desenvolvimento do NET Framework. Ele pode ser contatado em mmbeckner@inotekgroup.com.
Graças ao seguir técnico especialista para revisar este artigo: Scott Jones