Como aceder e alterar os valores dos dados das mensagens dentro das orquestrações

Aproveitando dois excelentes posts publicados pela Ruth de como aceder aos campos de uma mensagem através de XPath (que poderá ler aqui e aqui), partilho-vos um post que efetuei no passado no meu blog em inglês (podem encontrar as sources no MSDN Code Gallery)
Existem 3 formas de aceder e alterar os valores de uma mensagem dentro das orquestrações:
     · Utilizando propriedades promovidas (Property promotion)
     · Utilizando expressões XPath
     · Utilizando objetos C#/VB.NET (Serialization)
O último é o mais incomum, mas o podemos facilmente efectuar a serialização de uma mensagem num objecto C# como irá ser apresentado mais à frente neste post.

Utilizando propriedades promovidas (Property promotion)

Propriedades promovidas é a maneira mais fácil e rápida de aceder e alterar as dados de uma mensagem:

     · Fácil: Porque basicamente o utilizador não necessita de saber nada sobre a estrutura dos dados para aceder ao conteúdo dos elementos. Caso contrário teria de utilizar longas expressões XPath, susceptíveis a erros, para poder efetuar uma consulta aos dados da mensagem (aplicável às Property Fields e Distinguished Fields).

     · Rápido: Devido ao facto de não termos de carregar a mensagem inteira em memória para ter acesso aos seus dados. Estas propriedades serão colocadas dentro do contexto da mensagem através de uma coleção de pares: Chave – Valor (aplicável às Property Fields).
BizTalk Server fornece dois tipos de promoções de propriedade com base no que quer fazer com os dados:

     · Property Fields: são system wide, ou seja, são acessíveis em todas as fases do processamento de mensagens no BizTalk, seja em orquestrações, através de código personalizado, no encaminhamento de mensagens (message routing) ou nas pipelines.

     · Distinguished Fields: são propriedades que apenas são acessíveis dentro das orquestrações no entanto têm menos sobrecarga de execução comparadas com as anteriores.
Ambas são de leitura e escrita (read/write) fornecendo desta forma uma maneira fácil e rápida de aceder e alterar os valores de uma mensagem sem usar um mapa - como por exemplo atualizar um campo de estado.
Saiba mais aqui: Propriedades promovidas: Distinguished Fields vs. Property Fields


Como utilizar as Property Fields:

//Read
System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName)), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName) = "Sandro";

Como utilizer as Distinguished Fields:

//Read
System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput2.LastName), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
msgOutput2.LastName = "Pereira";

Utilizando expressões XPath

O BizTalk permite trabalhar com expressões XPath dentro das orquestrações de uma forma simples e extremamente poderosa, no entanto requer mais conhecimento e esforço por parte do programador em comparação com o uso de propriedades promovidas.
De igual forma que as propriedades promovidas, as expressões XPath também pode ser usadas para leitura e escrita de valores de uma mensagem, no entanto apenas podemos alterar os valores de uma mensagem necessitamos dentro de uma a Message Construct shape.
Uma das vantagens do uso de expressões XPath é que podemos executá-las contra mensagens sem tipo definido (untyped messages), i.e. mensagens que são definidas com o tipo System.Xml.XmlDocument. Sendo que podemos utilizar os resultados dessas expressões para definir outras mensagens, documentos XML ou variáveis existentes nas orquestrações.
Saiba mais aqui: XPath 1.0 Function Library Quick Reference, Operators and Special Characters Quick Reference
Para saber qual a expressão XPath que deve utilizar para aceder a um elemento da mensagem deve:
     · Aceder ao esquema (schema) e selecionar o elemento ou atributo desejado
     · Right-click e selecionar a opção “Properties”
     · Selecione a opção “Instance XPath” na janela de propriedades do elemento ou atributo

Como utilizar expressões XPath dentro de uma Message Assign shape:

//Read
System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(xpath(msgOutput3,"string(/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()=''])")), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
xpath(msgOutput3,"/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()='']") = "00";

Utilizando objetos C#/VB.NET (serialization)

O BizTalk é capaz de converter automaticamente e de forma simples mensagem XML em objetos C# e vice-versa, i.e. objetos C# em mensagem XML reconhecidas pelo BizTalk.
Para conseguirmos isso, temos de gerar classes C#/VB.NET com base nos esquemas usando a ferramenta XSD.EXE.
Nota 1: para aqueles que não estão familiarizados com o XSD.EXE: é uma ferramenta de linha de comando (command line tool) fornecido com o Visual Studio .NET que permite gerar classes ou Typed DataSets com base em XML Schemas
Nota 2: se estivermos a utilizar o BizTalk Server 2010/Visual Studio 2010 a classe que representa o esquema XML é automaticamente gerada.



Como criar uma classe a partir de um esquema (schema):
     · Start Menu -> All Programs -> Microsoft Visual Studio … -> Visual Studio Tools -> Visual Studio … Command Prompt
     · Navegar até a pasta que contêm o Schema e escreva o seguinte comando “xsd /classes /language:CS Schema1.xsd”

Criar uma variável dentro das orquestrações que representa a classe gerada
     · Primeiro temos de criar uma variável na orquestração que irá representar o tipo da classe que acabamos de criar
     · Para definir o tipo da mensagem devemos ir ás propriedades da variável e na opção “Type” selecionar a opção: “<.NET Class…>”

     · Na janela de escolha do tipo do artefacto, selecionar a livraria onde se encontra a classe e posteriormente a classe que representa o nosso schema.



Como utilizar objetos C# dentro de uma Message Assign shape

//CONVERT MESSAGE INTO C# OBJECT
varPersonMsg = msgInput;

//Read
System.Diagnostics.EventLog.WriteEntry("Orchestration", varPersonMsg.FirstName + " " + varPersonMsg.LastName, System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
varPersonMsg.FirstName = "Sandro";
varPersonMsg.LastName = "Pereira";
varPersonMsg.Age = "00";

//CONVERT C# OBJECT INTO BIZTALK MESSAGE
msgOutput4 = varPersonMsg;

Recursos

Código fonte deste exemplo disponível no MSDN Code Library.