Manual Framework NET MXM

Prévia do material em texto

Framework .NET MXM 
 
Framework .NET MXM Página 1 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
FRAMEWORK .NET MXM 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 2 
 
 
 
Histórico de Alterações 
Responsável Descrição Data Versão 
Samuel Macedo Criação do Documento 07/02/2011 1.0 
Samuel Macedo Inclusão de alterações na framework da 
versão 2.0.2.0 
16/12/2011 1.1 
Samuel Macedo Inclusão de informação sobre configuração da 
tecla F1 para o HelpField 
09/02/2012 1.2 
Samuel Macedo Inclusão de tópico sobre métodos de extensão 
do Ext.Net.MXMControls. 
27/02/2012 1.3 
Samuel Macedo Inclusão de tópico sobre MXM.WebService 20/03/2012 1.4 
Samuel Macedo Inclusão de informações sobre propriedade 
MXMDisabled nos controle MXMNumberField e 
MXMDateField 
28/03/2012 1.5 
Samuel Macedo Inclusão de informação sobre propriedade 
AutoTrim do FormBasic da web 
22/06/2012 1.6 
 Framework .NET MXM 
 
Framework .NET MXM Página 3 
 
 
 
Sumário 
 
1. A Framework .................................................................................................................................. 5 
1.1 Modelo de desenvolvimento (MVP) ........................................................................................... 5 
1.2 MAPs ......................................................................................................................................... 5 
1.2.1 MAPs comuns a todos os tipos de tela ............................................................................. 6 
Utilizado para mapear um link para uma tela de consulta. ............................................................ 10 
1.2.2 MAPs específicos de telas do tipo CRUD ....................................................................... 10 
1.2.3 MAPs específicos de telas de consulta ........................................................................... 11 
1.3 Classes básicas utilizadas pela framework ............................................................................. 12 
1.3.1 Persistência (MXM.Persistence) ...................................................................................... 12 
1.3.2 Classes de Ajuda ............................................................................................................. 15 
1.3.3 ErrorList ........................................................................................................................... 18 
1.3.4 Ambiente / AmbienteList .................................................................................................. 19 
1.3.5 Classe JavascriptService ................................................................................................. 20 
2. A camada de Apresentação (View) ............................................................................................. 21 
1.4 Classes de apresentação para implementação de tipos de tela específicos .......................... 22 
1.4.1 FormCRUD ...................................................................................................................... 22 
1.4.2 FormProcess .................................................................................................................... 23 
1.4.3 FormConsult .................................................................................................................... 24 
1.5 Classes de apresentação base ............................................................................................... 25 
1.5.1 FormBasic ........................................................................................................................ 25 
1.5.2 FormErrorList ................................................................................................................... 28 
1.5.3 FormMAPControl ............................................................................................................. 28 
1.6 Controles / Componentes ........................................................................................................ 30 
1.6.1 Web (Ext.Net.MXMControls) ........................................................................................... 30 
1.6.2 Windows .......................................................................................................................... 33 
1.6.3 Windows (MXM.Controls) ................................................................................................ 33 
1.6.4 Web (Ext.Net.MxmControls) ............................................................................................ 35 
3. A camada presenter .................................................................................................................... 35 
1.6.5 MainPresenter .................................................................................................................. 35 
1.6.6 MAPControlPresenter ...................................................................................................... 36 
1.7 Presenters associados a tipos específicos de telas ................................................................ 36 
1.7.1 Presenters CustomCRUDPresenter e CRUDPresenter .................................................. 36 
1.7.2 Presenters CustomProcessPresenter e ProcessPresenterPersistence .......................... 38 
1.7.3 Presenters CustomConsultPresenter e ConsultPresenter .............................................. 39 
1.7.4 Interface IDBPresenterControl / Classe PersistControl ................................................... 39 
4. A camada Model .......................................................................................................................... 41 
1.8 Classes de Persistência .......................................................................................................... 41 
1.8.1 Mapeando classes ........................................................................................................... 41 
1.9 Classes de Validação .............................................................................................................. 50 
1.9.1 Métodos de validação ...................................................................................................... 50 
1.9.2 Método ProcessValidate .................................................................................................. 50 
1.9.3 Classes de validação que utilizam Persist ...................................................................... 51 
1.10 Classes de Consulta (MXMConsult) .................................................................................... 51 
1.10.1 Constructors ..................................................................................................................... 51 
1.10.2 Métodos ........................................................................................................................... 52 
1.10.3 Exemplo de utilização da MainConsult diretamente para executar queries ................... 52 
1.10.4 Exemplo de implementação e utilização classe de consulta herdando de MainConsult 53 
1.11 Classes de Processo (MainProcess / ProcessErrorList) ..................................................... 53 
5. Outras classes ............................................................................................................................. 54 
1.12 MXM ..................................................................................................................................... 54 
1.12.1 Funcionalidades ............................................................................................................... 54 
1.13 MXM.Audit ........................................................................................................................... 58 
1.14 MXM.Objects .......................................................................................................................59 
1.15 MXM.Connection ................................................................................................................. 59 
 Framework .NET MXM 
 
Framework .NET MXM Página 4 
 
 
1.15.1 Classe DBConnection ...................................................................................................... 59 
1.16 MXM.Unmanaged ................................................................................................................ 60 
1.17 MXM.WebSite ...................................................................................................................... 61 
1.17.1 Login e página principal ................................................................................................... 61 
1.17.2 Classe DashBoard ........................................................................................................... 61 
1.17.3 JQuery ............................................................................................................................. 61 
1.18 MXM.WebService ................................................................................................................ 62 
6. Utilitários ...................................................................................................................................... 62 
1.19 Registro de Ambientes ........................................................................................................ 62 
1.19.1 Aba Ambientes ................................................................................................................. 62 
1.19.2 Aba LDAP ........................................................................................................................ 64 
7. Guia de Utilização e Exemplos .................................................................................................... 65 
1.20 Configuração do ambiente de desenvolvimento ................................................................. 65 
1.21 Criação de novos projetos ................................................................................................... 65 
1.21.1 Criando um novo projeto desktop .................................................................................... 65 
1.21.2 Criando um novo projeto Web ......................................................................................... 65 
1.21.3 Criando classes de persistência ...................................................................................... 65 
1.21.4 Criando classes de validação .......................................................................................... 76 
1.21.5 Criando classes de ajuda ................................................................................................ 86 
5.1 Implementação de telas ........................................................................................................... 90 
5.1.1 Implementando uma tela de cadastro (CRUD) ............................................................... 90 
2.1.1 Implementando uma tela de consulta ............................................................................ 105 
2.1.2 Implementando uma tela de processo .......................................................................... 108 
2.1.3 Implementando um presenter e utlizando-o em uma tela ............................................. 108 
2.2 F.A.Q. ..................................................................................................................................... 108 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 5 
 
 
1. A Framework 
1.1 Modelo de desenvolvimento (MVP) 
 
 
 
 A framework .NET MXM utiliza o modelo de desenvolvimento MVP (Model, View, 
Presenter). Nesse modelo, o desenvolvimento é dividido em três camadas: View, que é a 
camada de apresentação e deve conter o código relacionado à interface com o usuário, Model 
que é o modelo de dados da aplicação e Presenter, que atua como uma camada intermediária 
entre o Model e o View. A framework MXM possui versões para Windows e web, de forma que 
existem classes base de apresentação separadas para cada plataforma. Existem, dessa forma, 
duas versões de cada uma dessas classes com as mesmas funcionalidades, porém estão 
contidas em assemblies distintos, um para Windows e um para web, implementando as 
particularidades de cada plataforma (os nomes dessas classes em geral são precedidos da 
palavra “Form”, p. ex., FormBasic, FormErrorList, etc). A camada Presenter contém as rotinas 
intermediárias entre a camada View e a Model, e é independente de plataforma, uma vez que 
todo o código relacionado às telas está contido na camada View, sendo utilizados os mesmos 
Presenters tanto para web quanto para Windows. A camada Model corresponde às classes de 
persistência e às demais classes que trabalham em contato direto com o modelo de dados, 
como classes de processo, consulta, etc. 
1.2 MAPs 
O MAP é um recurso utlizado pela framework para mapear elementos da camada de 
apresentação para elementos das camadas model / presenter e fornecer à framework 
informações em geral sobre a tela, possibilitando que parte do processamento seja realizado 
de forma automatizada, sem intervenção do desenvolvedor. Dessa forma, como será visto 
mais adiante, em uma tela de cadastro, por exemplo, o desenvolvedor não irá precisar 
preencher as classes de persistência manualmente com os valores contidos nos campos da 
tela: através do uso de MAPs específicos ele apenas informará qual controle está ligado a qual 
propriedade da classe, e a criação do objeto será feita automaticamente. 
Esses MAPs são atributos definidos para as classes e suas propriedades, e são lidos pela 
framework através de reflection. Em geral pertencem ao namespace MXM.Presenter, do 
assembly MXM.Presenter. 
 Framework .NET MXM 
 
Framework .NET MXM Página 6 
 
 
1.2.1 MAPs comuns a todos os tipos de tela 
 
1.2.1.1 MAPIDFunction 
 
 
Utilizado para informar o código da função da tela. É importante informar este código em 
todas as telas, pois o mesmo é utilizado pela framework para diversos fins, como controle de 
acesso e auditoria. 
 
Parâmetros Descrição 
ID ID da função (corresponde ao valor da coluna MXF_FUNCAO da tabela 
MXS_FUNCAO_MXF). 
 
1.2.1.2 MAPClass 
 
Utilizado para informar a classe da camada model com que se está trabalhando em uma 
determinada tela. No caso de telas CRUD, por exemplo, a classe de persistência e a classe de 
validação. 
 
Parâmetros Descrição 
ClassType Informar o tipo (TypeOf) da classe com que se irá trabalhar na tela. 
ValidatorType Informar o tipo da classe de validação em telas do tipo CRUD (não utilizado 
nas demais telas). 
 
1.2.1.3 MAPControl 
 
 
Mapeia um controle da tela, relacionando-o ou não a uma propriedade em uma classe. A 
finalidade de se mapear um controle é permitir que as tarefas mais comuns, como a limpeza 
do controle após o processamento ou exclusão, por exemplo, sejam realizadas de forma 
automatizada pela framework, e caso o mesmo esteja relacionado a propriedade de uma 
classe, permitir que a mesma seja preenchida automaticamente com o valor do controle na 
tela. Controles não mapeados serão ignorados pela framework, sendo necessário manipulá-los 
manualmente. 
 
Parâmetros Descrição 
ControlName Informar o nome (ID na web / Name no Windows Forms) do controle. 
 Framework .NET MXM 
 
Framework .NET MXM Página 7 
 
 
PropertyName Informar a propriedade na classe de persistência que irá receber o valor 
contido no controle (opcional). 
WindowHelp Caso o controle possua janela de ajuda (TextBox com F1 no Windows ou 
HelpFieldna web), informar o tipo (TypeOf) da classe de ajuda. 
LinkFunctionID Caso o campo seja um HelpField, para linkar uma outra funcionalidade 
ao mesmo informe o ID da função da tela que será aberta (por 
exemplo, para um HelpField de empresa fornecer um botão com link 
para tela de cadastro de empresa, passe o ID da função da tela de 
cadastro de empresa). 
LinkValueProperty Propriedade na classe de persistência que será aberta correspondente 
ao valor inserido no controle. 
 
1.2.1.4 MAPListControl 
 
 
Semelhante ao MAPControl, porém mapeia um controle que contém uma lista de itens 
(ComboBox, ListBox, etc), associando-a a um enum que contém os dados destes itens, 
mapeado conforme descrito abaixo. Isto permite que esses itens sejam manipulados 
automaticamente pela framework. Este MAP é suportado apenas pela framework 
Windows. 
 
Parâmetros Descrição 
EnumType Tipo (typeof) do enum relacionado ao 
controle. 
 
Esses Enums devem ser criados da seguinte forma: 
 
1. O Enum deverá possuir o atributo [EnumDescription(typeof(Properties.EnumDesc))]. 
2. Cada item do enum deverá possuir um atributo do tipo EnumValue. Como parâmetro 
para esse atributo deverá ser informado o valor que efetivamente será passado para a 
classe model quando o item correspondente for selecionado no controle na tela. 
3. Além de criar o Enum, também é necessário definir a descrição (o que realmente 
aparecerá para o usuário na tela nos itens do controle) para cada item do enum. Isso é 
feito utilizando o resource EnumDesc.resx, localizado na pasta Properties do projeto 
que contém o enum. Esse arquivo deverá conter uma linha para cada item do enum, de 
forma que a coluna "Name" de cada uma dessas linhas possua exatamente o nome do 
item, e a coluna "Value" possua a descrição. 
 Framework .NET MXM 
 
Framework .NET MXM Página 8 
 
 
1.2.1.5 MAPGridClass 
 
 
Utilizado para mapear grids, relacionando a grid a uma classe, e opcionalmente a uma 
propriedade na classe associada à tela. Como telas CRUD trabalham diretamente com classes 
de persistência, e nessas classes é possível identificar o tipo da classe através de atributos da 
própria classe de persistência (através dos atributos OneToMany e ManyToMany), não sendo 
necessário nestes casos utilizar este atributo: basta utilizar o atributo MAPControl relacionando 
a grid à propriedade na classe que contém a lista que está relacionada à grid. Nas demais telas 
deve-se utilizar o MAPGridClass. Esse MAP só é suportado pela framework Windows. Em telas 
web a grid deverá ser manipulada manualmente. 
 
1.2.1.6 MAPControlDescription 
 
 
Utilizado para mapear campos do tipo “código / descrição”, para que a descrição seja 
buscada automaticamente. 
 
Parâmetros Descrição 
ClassType Tipo (typeof) da classe de persistência que será utilizada para buscar 
a descrição. 
ControlName Nome do controle que contém o código. 
PropertyName Propriedade na classe definida em ClassType correspondente ao 
código / chave (o código digitado no MXMTextBox alvo deverá ser 
igual ao valor dessa propriedade). 
 
PropertyDescription Propriedade na classe definida em ClassType correspondente à 
descrição (o valor dessa propriedade será exibido no MXMTextBox que 
está sendo mapeado). 
 
 
 
1.2.1.7 MAPControlValidation 
 
 Permite criar uma validação para o controle, associando o controle a um método numa 
classe de validação. Essa validação será executada ao sair do controle, sendo exibidas na tela 
as mensagens contidas no ErrorList passado como parâmetro para o método. 
 Framework .NET MXM 
 
Framework .NET MXM Página 9 
 
 
 
 
Parâmetros Descrição 
ParameterControls 
 
Deve ser utilizado para mapear controles na tela cujos conteúdos 
serão passados como parâmetros para o método de validação. Passar 
um array de String com os nomes dos controles. 
TargetControl 
 
Nome do controle que será validado. 
ValidationClass 
 
Tipo (TypeOf) da classe que contém o método de validação. 
ValidationMethod 
 
Nome do método de validação. 
RequiresConnection 
 
Define se o método precisa de conexão com o banco. 
 
O método de validação deve ser estático (static) e seus parâmetros devem obedecer ao 
seguinte padrão: 
 
• Os primeiros 0 a N parâmetros receberão o conteúdo dos controles mapeados através 
da propriedade “ParameterControls” do MAP, conforme explicado acima. Dessa forma, o 
método de validação deve esperar receber como primeiros parâmetros exatamente a 
mesma quantidade de itens e na mesma ordem em que aparecem no array passado 
para ParameterControls. 
 
• O primeiro parâmetro após estes 0 a N, irá receber o conteúdo do controle que está 
sendo validado. 
 
• O próximo parâmetro deverá ser do tipo ErrorList. A esta ErrorList deverão ser 
adicionados os erros encontrados na validação. Ao fim da validação, estes erros serão 
exibidos na tela. 
 
• Caso o método precise de conexão com o banco (RequiresConnection = true), o método 
ainda deverá esperar mais um últmo parâmetro do tipo Persistence, que irá ser 
passado com a conexão já aberta. 
1.2.1.8 MAPPresenter 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 10 
 
 
Utilizado para mapear um presenter implementado pelo usuário. A não ser que seja 
criado um presenter a parte, herdando dos presenters padrão da framework e implementando 
novas funcionalidades, não é necessário utilizar este MAP, bastando utilizar o MAPClass para 
que o presenter padrão de cada tipo de tela seja criado automaticamente. 
 
Parâmetros Descrição 
PresenterType 
 
Tipo (TypeOf) do presenter 
1.2.1.9 MAPConsultLink 
Utilizado para mapear um link para uma tela de consulta. 
Parâmetros Descrição 
ConsultButtonID ID do botão que chmará a tela de consulta 
FunctionID ID da função corrspondente à tela de consulta 
LoadFiltered True para que a consulta já venha filtrada pelos campos mapeados, 
false para apenas carregar os valores dos campos mapeados nos filtros 
correspondentes 
1.2.1.10 MAPConsultFilter 
 
Permite mapear os campos que serão utilizados como filtros na tela mapeada através do 
MAPConsultLink. 
 
Parâmetros Descrição 
ControlName ID do controle na tela onde está sendo feito o mapeamento que será 
usado como filtro 
DestinyControlName Nome do controle na tela destino que receberá o valor contido no 
controle mapeado pelo ControlName 
 
1.2.2 MAPs específicos de telas do tipo CRUD 
1.2.2.1 MAPControlKey 
 
Semelhante ao MAPControl, porém mapeia um controle que está relacionado a uma 
propriedade na classe de persistência que corresponde a uma chave (PK) na tabela. É utilizado 
apenas em telas CRUD, já que somente essas telas trabalham diretamente com classes de 
persistência. 
 
Parâmetros Descrição 
 Framework .NET MXM 
 
Framework .NET MXM Página 11 
 
 
LoadSaveRecord Caso seja definido como “true”, ao sair do controle serão carregados nos 
campos da tela os valores do registro com chave equivalente aos valores 
digitados nos campos mapeados como MAPControlKey. 
Nullable Se true, define que ao sair do campo será disparado o carregamento da 
tela mesmo que o controle esteja vazio. É opcional e seu uso deve ser 
evitado, tendo sido implementado apenas para dar suporte a telas que 
trabalham com tabelas já existentes com modelagem errada. 
 
Demais parâmetros funcionam de maneira idêntica a MAPControl, sendo obrigatório informar o 
PropertyName. 
1.2.2.2 MapCommandInformedIndex 
 
Permite mapear índice utilizado ao fazer a busca de uma tela CRUD utilizando uma 
classe que implementa ICommandInformed. O parâmetro corresponde ao índice que será 
passadoao buscar a classe. 
1.2.3 MAPs específicos de telas de consulta 
1.2.3.1 MAPColumnTitle 
 
Mapeia as colunas da consulta e dados em geral sobre a exibição de cada coluna na 
exportação (alinhamento, formatação, etc). 
 
Parâmetros Descrição 
Column Nome da coluna no store. 
Title Título da coluna, da forma como deverá aparecer ao exportar a consulta 
para um arquivo Excel ou pdf. 
Format Formato como será exibida a informação ao exportar (p. ex. 
“dd/MM/yyyy”). 
IsGroup Se a consulta deverá ser agrupada pela coluna. Uma consulta pode ter 
mais de um grupo. 
Ordem Ordem em que a coluna será exibida ao exportar. 
SummaryType Caso a coluna possua um totalizador, informe o tipo de totalizador 
(somatório ou contagem). 
SummaryLabel Informa, se for o caso, o texto que irá aparecer antes do totalizador. 
Align Alinhamento da coluna ao exportar (direita, esquerda ou centralizado). 
Width Largura da coluna 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 12 
 
 
1.2.3.2 MAPExportConfig 
 
Utilizado para fornecer informações sobre o arquivo exportado. 
 
Parâmetros Descrição 
Title Título que será exibido no arquivo exportado 
Filename Nome (físico) do arquivo 
ShowTitleInPdfFile Defina se será exibido título no arquivo gerado ao exportar a 
consulta para pdf 
ShowTitleInExcelFile Defina se será exibido título no arquivo gerado ao exportar a 
consulta para Excel 
ShowDateInPdfFile Defina se será exibida data no arquivo gerado ao exportar a consulta 
para pdf 
ShowDateInExcelFile Defina se será exibida data no arquivo gerado ao exportar a consulta 
para Excel 
FonteHeader Tamanho da fonte no header 
FonteRow Tamanho da fonte das linhas 
Orientacao Orientação (“R” para retrato ou “P” para paisagem) 
 
1.3 Classes básicas utilizadas pela framework 
1.3.1 Persistência (MXM.Persistence) 
 
A classe MXM.Persistence tem como objetivo tornar a comunicação com o banco de 
dados totalmente orientada a objetos para o desenvolvedor. Após mapear as tabelas do banco 
para classes de persistência seguindo uma série de regras definidas a seguir, o desenvolvedor 
não precisará lidar diretamente com comandos de banco, como selects, inserts, etc, para 
manipular estas tabelas, podendo trabalhar diretamente com as classes mapeadas e com uma 
instância da classe "Persistence" (MXM.Persistence.Persistence), que encapsula todos esses 
comandos, fazendo com que o desenvolvedor possa obter resultados semelhantes através de 
métodos desta classe. 
 
1.3.1.1 Constructor 
 
O constructor desta classe aceita como parâmetro um objeto da classe 
“MXM.Connection.Ambiente”. Ao instanciá-la, a conexão com o banco de dados será 
automaticamente aberta, sendo imprescindível utilizá-la dentro de um bloco “using” 
para que a conexão seja fechada ao sair do mesmo, sempre que instanciada manualmente. 
 Framework .NET MXM 
 
Framework .NET MXM Página 13 
 
 
 
1.3.1.2 Buscando dados do banco 
 
A busca de dados é feita utilizando-se as classes de persistência. Em geral, utiliza-se 
uma instância de uma dessas classes como filtro, ou seja, instancia-se a classe de 
persistência, preenchendo apenas as propriedades que serão utilizadas no filtro. As demais 
propriedades serão ignoradas. Por exemplo, se eu possuo uma classe "Venda" que possui as 
propriedades "Codigo", "Data", "CodigoCliente" e "Observacao", e quero obter todas as vendas 
realizadas no dia 13/05/2009 pelo cliente de código "2", crio uma nova instancia desse classe 
para utilizar como filtro (Venda v = new Venda()) e preencho apenas a propriedades 
relacionadas a busca que quero executar ("Data" e "CodigoCliente": v.Data = new 
DateTime(2009,5,13); v.CodigoCliente = 2;), deixando as outras propriedades não 
preenchidas (null). Este objeto deverá ser passado para um dos métodos de busca da classe 
Persistence para que seja executada a busca (no caso do exemplo, seria utilizado o 
"GetObjects" que retoria uma lista de objetos da classe Venda com todas as propriedades 
preenchidas relativos a todos os registros na tabela associada a esta classe que possuam a 
data igual a 13/05/2009 e o código do cliente igual a 2). 
 
1.3.1.2.1 Realizando uma busca que retorna apenas um objeto 
 
Para realizar uma busca que retorne apenas um objeto (ao buscar pela chave primária 
por exemplo) deve-se utilizar o método “GetObject”, que retorna um objeto do tipo object 
(deve ser feito typecast para o tipo original) caso seja encontrado um registro na tabela 
correspondente ao padrão de busca utilizado ou null caso nenhum registro seja encontrado. 
1.3.1.2.2 Retornando uma lista de objetos que obedeçam a um padrão 
 
Para obter uma lista de objetos correspondentes a um conjunto de registros de uma 
tabela que obedeçam ao padrão estabelecido, deve-se utilizar o método “GetObjects”, que 
retorna uma lista de objetos do tipo “object” (deve ser feito typecast em cada um deles para o 
tipo original). Se nenhuma row obedecer o padrão será retornada uma lista vazia. 
 
1.3.1.2.3 Retornando uma lista com objetos correspondentes a todas as rows da 
tabela 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 14 
 
 
Para obter uma lista com objetos correspondentes a todos os registros da tabela 
relacionada a uma classe, utilize o método “GetAllObject”. Este método retorna uma lista 
semelhante a retornada pelo método “GetObjects”. 
 
1.3.1.3 Persistência de objetos 
 
1.3.1.3.1 Iniciando uma transação 
 
Utilize o método “StartTransaction”. 
1.3.1.3.2 Salvando um objeto (criando novos registros) 
 
Para salvar objetos no banco (criar novos registros, semelhante ao comando INSERT), 
utilize o método “Save”. Este método possui 2 sobrecargas, uma que aceita apenas um objeto 
(será criado um novo registro na tabela correspondente ao objeto) e outra que aceita uma lista 
de objetos (será criado um novo registro na tabela para cada objeto da lista). As propriedades 
da classe correspondentes às primary keys que utilizarem geração automática não deverão ser 
preenchidas, já que seu valor será gerado automaticamente. 
1.3.1.3.3 Persistindo alterações realizadas em um objeto (alterando registros já 
existentes) 
 
Para persistir alterações realizadas em objetos (alterar registros já existentes, 
semelhante ao comando UPDATE), utilize o método “Update”. Este método possui 2 
sobrecargas, uma que aceita apenas um objeto (o registro correspondente ao objeto será 
atualizado) e outra que aceita uma lista de objetos (todos os registro correspondentes a todos 
os objetos da lista serão alterados). É importante que estes objetos estejam com as 
propriedades relacionadas a chaves primárias preenchidas corretamente. 
1.3.1.3.4 Excluindo registros associados a objetos 
 
Para excluir registros associados a objetos, deve-se utilizar o método “Delete”. Este 
método possui 2 sobrecargas, uma que aceita apenas um objeto (o registro associado ao 
objeto será excluído) e outra que aceita uma lista de objetos (todos os registro 
correspondentes a todos os objetos da lista serão excluídos). 
 Framework .NET MXM 
 
Framework .NET MXM Página 15 
 
 
1.3.1.3.5 Executando Commit 
 
Utilize o método “Commit”. 
1.3.1.3.6 Executando Rollback 
 
Utilize o método “Rollback”. 
1.3.1.3.7 Fechando a conexão com o banco 
 
A conexão é fechada através do método “Close”, porém, como a Persistence deve 
sempre ser usada dentro de um bloco “using”, não é necessário chamar esse método 
explicitamente, pois a mesma será fechada ao fim do bloco. 
1.3.2 Classes de Ajuda 
 
As classes de ajuda são utilizadas em conjunto com controles específicos (HelpField na 
web e MXMTextBox no Windows). Controlesdesse tipo permitem a exibição uma tela de 
consulta que pode ser utilizada pelo usuário para buscar os valores disponíveis para o controle. 
Os dados dessa consulta são configurados através de classes de ajuda, que devem herdar da 
classe abstrata MainHelpConfig, que pertence ao namespace MXM.Objects.Help, do assembly 
MXM.Objects. Segue abaixo uma descrição de como implementar as classes de ajuda. Para 
descrição de como utilizá-las e associá-las aos controles, consulte tópico correspondente. 
 
1.3.2.1 Implementando classe de ajuda 
 
1. Crie uma classe herdando de MainHelpConfig. 
 Framework .NET MXM 
 
Framework .NET MXM Página 16 
 
 
2. Essa classe deverá possuir um constructor que recebe um parâmetro inteiro (índex). 
Esse parâmetro será passado para a propriedade Index, que pode ser utilizada em 
qualquer método da classe para permitir que uma mesma classe de ajuda tenha um 
funcionamento diferente dependendo do valor passado. Por exemplo, uma mesma 
classe de ajuda pode ser utilizada em duas telas, possuindo uma condição 
(propriedade Where) diferente em cada uma. Dessa forma, poderia passar valores 
diferentes para o parâmetro index em cada tela e utilizá-lo no método SetupProperty 
(descrito em seguida) para, através de um “if” ou “switch” definir o valor da minha 
propriedade “Where”. 
 
3. Implemente o método SetupProperty de MainHelpConfig (override). Nesse método 
deverão ser preenchidas as propriedades da classe com as informações gerais da 
consulta. As propriedades são as seguintes: 
 
Propriedade Descrição 
Title Título que será exibido na tela de consulta 
KeyField Campo chave, correspondente ao código na tabela em que será realizada a 
busca (nome da coluna da tabela, p. ex. MXU_USUARIO) 
DescriptionF
ield 
Campo correspondente à descrição (nome da coluna da tabela, p. ex. 
MXU_NOME) 
From Tabelas utilizadas na consulta separadas por vírgula (correspondente ao from 
da query). 
Where Condição da consulta, exatamente como apareceria no where da query. Caso 
a condição dependa de valores de outros campos da tela, ou de valores que 
serão definidos apenas na camada de apresentação, utilize parâmetros 
(:NOME_DO_PARAMETRO) na query para esses valores (p. ex. Where = 
“MXU_USUARIO = :CODIGOUSUARIO”. 
OrderBy Campos utilizados para ordenação separados por vírgula (equivalente ao order 
by da query) 
Distinct Boolean. Utilizado para definir se será incluído distinct na query, para não 
trazer valores repetidos. 
public class WHExemplo : MainHelpConfig 
{ 
public WHExemplo(Int32 index) : base(index) { } 
... 
 Framework .NET MXM 
 
Framework .NET MXM Página 17 
 
 
 
 
4. Implemente o método CreateHelpFields de MainHelpConfig (override). Nesse método 
deverão ser definidos os campos da consulta, inserindo instâncias da classe 
HelpConfigField na propriedade Fields. O constructor dessa classe possui os 
seguintes parâmetros: 
 
Parâmetro Descrição 
Name / 
Alias 
Caso seja necessário manipular o valor da coluna na query (utilizando um 
decode ou nvl por exemplo), deve-se utilizar o campo Name para 
informar o valor e o parâmetro Alias para informar um nome para a 
coluna (existem construtores com e sem o parâmetro Alias). Do 
contrário, utilize o constructor sem o parâmetro Alias e apenas passe o 
nome da coluna para Name. 
Description Descrição da coluna, conforme deverá aparecer no título da grid em que 
serão exibidos os resultados da consulta 
Type Tipo da coluna 
Width Largura da coluna 
protected override void SetupProperty() 
{ 
Title = "Exemplo"; 
 
KeyField = "EXE_CODIGO"; 
DescriptionField = "EXE_NOME"; 
 
WindowHeight = 300; 
WindowWidth = 700; 
RegistersPerPage = 10; 
From = "EXEMPLO_EXE, OUTROEXEMPLO_OEX"; 
 
 Where = "EXE_OUTROEXEMPLO = OEX_CODIGO"; 
 
if (Index == 0) 
{ 
 Where += "AND OEX_VALORX = 1"; 
} 
} 
 Framework .NET MXM 
 
Framework .NET MXM Página 18 
 
 
 
1.3.3 ErrorList 
Representa uma lista de mensagens e é utilizada em diversos momentos pela 
framework, por exemplo nas classes de validação para adicionar os erros encontrados ou 
diretamente pelo desenvolvedor para exibir mensagens para o usuário. 
1.3.3.1 Métodos 
 
Método Descrição 
AddFatalError Adiciona um erro à lista de mensagens. Como 
parâmetros devem ser passados o código do erro e a 
mensagem. 
AddWarningMessage Adiciona um warning à lista de mensagens. Como 
parâmetros devem ser passados o código do warning e 
a mensagem. 
AddMessage Adiciona uma mensagem à lista de mensagens. Como 
parâmetros devem ser passados o código do warning e 
a mensagem. 
AddExceptionError Permite adicionar a mensagem de uma exceção à lista 
de mensagens passando a exceção como parâmetro. 
RemoveDuplicateMessages Remove mensagens duplicadas 
 
1.3.3.2 Propriedades 
 
Propriedade Descrição 
HasFatalErro Valor booleano. Pode ser usado para consultar se existem erros na 
lista. 
 
protected override void CreateHelpFields() 
{ 
Fields.Add(new HelpConfigField("EXE_CODIGO", "Código", typeof(Int32), 
100)); 
Fields.Add(new HelpConfigField("EXE_NOME", "Nome", typeof(String), 
250)); 
Fields.Add(new HelpConfigField("SUBSTR(OEX_PERIODO,0,2) || '/' || 
SUBSTR(OEX_PERIODO,3,4)", "OEX_PERIODO", "Período", typeof(String), 150)); 
Fields.Add(new HelpConfigField("NVL(OEX_TIPO,'Sem Tipo')", 
"OEX_NMTPDOCUMENTO", "Tipo", typeof(String), 150)); 
} 
 Framework .NET MXM 
 
Framework .NET MXM Página 19 
 
 
1.3.3.3 Resources de mensagens de erros 
 
Por padrão, as mensagens que serão passadas para o segundo parâmetro dos métodos 
AddFatalError, AddWarningMessage e AddMessage devem ficar em um resource de nome 
Message.resx dentro da pasta Properties do projeto que contém a classe correspondente à 
mensagem. Dessa forma, as mensagens nunca deverão ser passadas diretamente como uma 
String para esse parâmetro (“p. ex. “Erro exemplo”), sendo passado apenas o valor no 
resource (p. ex. Properties.Message.CODIGO_DA_MENSAGEM). 
1.3.4 Ambiente / AmbienteList 
A classe Ambiente armazena dados em geral sobre a aplicação, como nome e senha do 
usuário logado por exemplo, e dados sobre a conexão com o banco de dados. Uma aplicação 
pode trabalhar com um ou mais ambientes (caso a aplicação conecte em mais de uma base). A 
classe AmbienteList representa uma lista desses ambientes. Todas as classes da framework 
em que é possível trabalhar com o banco de dados, como as classes da camada de 
apresentação, classes de processo, etc, possuem propriedades do tipo Ambiente (Amb), 
AmbienteList (AmbList) e um inteiro (AmbIndex) que é utilizado para indexar a lista AmbList 
obtendo um dos ambientes. Dessa forma, por exemplo, na camada de apresentação de uma 
tela de cadastro, que irá herdar da classe FormCRUD, posso obter o nome do usuário logado 
usando Amb.Username, onde Amb é uma propriedade do tipo Ambiente da própria classe. 
Conforme será visto em local apropriado, a instância das classes que trabalham diretamente 
com o banco (como Persistence e MainConsult por exemplo) geralmente é feita passando-se 
um desses objetos como parâmetro. Dessa forma, se na mesma classe do exemplo anterior o 
desenvolvedor precisar criar uma instancia de MainConsult para executar uma query, para 
instanciá-la bastaria passar a propriedade AmbList para o constructor. A classe Ambiente 
possui as seguintes propriedades: 
 
Propriedade Descrição 
ConnectionString ConnectionString do ambiente 
ConnectionStringDataBase ConnectionString com informações específicas do tipo de 
banco. 
Culture String com cultura do usuário logado (p. ex. “Pt-Br”) 
DataBaseType Tipo debanco (Oracle, SQLServer, etc). 
EmailUser E-mail do usuário logado. 
Name Nome do usuário logado. 
Password Senha do usuário logado. 
 Framework .NET MXM 
 
Framework .NET MXM Página 20 
 
 
Produto Produto (tabela MXS_PRODUTO_MXP) da aplicação. 
SaveAudit Não utilizado atualmente. 
SetRole Não utilizado atualmente. 
Tag Utilizado em determinadas aplicações para passar 
informações adicionais ao ambiente. 
UserName Código do usuário logado (MXU_USUARIO). 
ValidatePasswordInDatabase Se a validação de senha do usuário é feita no banco (true) 
ou na tabela (MXS_USUARIO_MXU) para esse ambiente. 
 
1.3.5 Classe JavascriptService 
Utilize a classe JavascriptService do arquivo MXM.Web.Javascript para registrar os 
javascripts de utilitários da framework. Essa classe possui 2 métodos, RegisterBasicUtils, para 
registrar os scripts básicos e RegisterGridUtils para utilitários para trabalhar com grids (para 
usar o segundo é obrigatório usar o primeiro). 
Esse métodos devem ser chamados no OnPreRender da página e deve ser passada a 
página para eles como parâmetro. 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 21 
 
 
2. A camada de Apresentação (View) 
 
 
 
Todas as classes correspondentes à camada de apresentação deverão herdar de uma das 
classes base definidas pela framework para este fim. Dessa forma, as classes, que herdariam 
diretamente de System.Windows.Forms.Form para Windows Forms e System.Web.UI.Page 
para ASP.Net, deverão herdar de uma das classes de apresentação da framework. Essas 
classes estão contidas no namespace MXM.Win.Forms / Assembly MXM.Win.Forms para telas 
Windows e MXM.Web.Coolite.Forms / Assembly MXM.Web.Coolite.Forms para telas web. 
A implementação das classes de apresentação nunca será feita no mesmo projeto da 
aplicação principal (no caso da web, do website), que conterá apenas referências para os 
assemblies que contém a implementação propriamente dita das telas. No caso da web, como 
os arquivos aspx e seus arquivos .cs associados não podem ficar em um assembly separado, 
apenas estes deverão ficar no website. O arquivo .cs associado ao aspx não deverá conter 
praticamente nenhum código, apenas a definição da classe associada ao aspx herdando da 
classe de apresentação, que deverá ser implementada em um assembly / projeto distinto 
 Framework .NET MXM 
 
Framework .NET MXM Página 22 
 
 
(consulte tópico sobre o FormBasic para informações sobre como acessar os controles do aspx 
em um projeto separado). 
1.4 Classes de apresentação para implementação de tipos de tela específicos 
Existem classes base de apresentação para os tipos mais comuns de tela, como telas de 
cadastro (CRUD), processo, consulta e relatório. Ao implementar essas classes, grande parte 
da funcionalidade da tela será controlada automaticamente pela framework, bastando ao 
desenvolvedor montar a tela (design) e utilizar os MAPs corretamente. Todas essas classes 
possuem um presenter associado, sendo possível ao desenvolvedor interferir no 
funcionamento da tela através da utilização de eventos desse presenter (descritos no tópico 
apropriado) e da sobrecarga de métodos específicos de cada tipo de tela, que serão 
relacionados nos tópicos correspondentes. 
 
1.4.1 FormCRUD 
 A classe “FormCRUD” permite a implementação da camada de apresentação de telas do 
tipo CRUD (Create, Read, Update, Delete – Criação, Consulta, Alteração e Exclusão), ou seja, 
telas de cadastro e alguns tipos de processo. Para utilizá-la, a classe correspondente a camada 
de apresentação deverá herdar de FormCRUD. Nas telas web é necessário criar botões com os 
nomes (ID) padrão utlizados pela classe (btGravar para o botão que irá salvar / atualizar, 
btExcluir para o botão que irá apagar os registros e btPrint para o botão utilizado para imprimir 
listagem dos registros que são cadastrados pela tela). Nas telas Windows isso não é 
necessário, pois os botões ficam diretamente em FormCRUD, sendo utilizada herança de form. 
Essa classe sempre irá trabalhar em conjunto com uma classe de persistência e uma 
classe de validação (camada model), de forma que o MAPClass deverá ser utilizado para 
mapear classes desses dois tipos. Ao utilizar o MAPClass dessa forma, será instanciado um 
presenter do tipo padrão utilizado pela tela automaticamente (CRUDPresenter). O 
desenvolvedor poderá ainda implementar um presenter herdando de CRUDPresenter e utilizar 
o MAPPresenter para mapeá-lo, não sendo necessário utilizar o MAPClass nesse caso. 
Para maiores detalhes sobre o presenter CRUDPresenter consulte o tópico apropriado. 
1.4.1.1 Métodos 
 
Método Parêmetros Retorno Descrição 
GetRecordInControl RecordList void Permite ao desenvolvedor interferir no 
carregamento dos objetos da lista de 
 Framework .NET MXM 
 
Framework .NET MXM Página 23 
 
 
objetos que será persistida no banco para, 
por exemplo, alterar propriedades, 
preencher propriedades com valores 
padrão, preencher propriedades com dados 
de controles não suportados pela 
framework, etc. Para isso basta alterar 
diretamente os objetos contidos em 
RecordList (passado como parâmetro). Nas 
telas de cadastro de apenas um item 
(maioria das telas), esta lista conterá 
apenas a posição 0. 
SetRecordInControl RecordList void Permite ao desenvolvedor interferir no 
carregamento dos controles da tela com 
registros da lista contendo objetos com 
dados vindos do banco para, por exemplo, 
preencher controles na tela que não são 
suportados pela framework. Para isso basta 
verificar os dados dos itens da lista. Nas 
telas de cadastro de apenas um item 
(maioria das telas), esta lista conterá 
apenas a posição 0. 
 
1.4.2 FormProcess 
A classe “FormProcess” permite a implementação da camada de apresentação de telas 
de processo. Para utilizá-la, a classe correspondente a camada de apresentação deverá herdar 
de FormProcess. Nas telas web é necessário criar botões com os nomes (ID) padrão utlizados 
pela classe FormProcess (btPtrocess para o botão que irá executar o processamento e 
btUndoProcess para o botão que irá desfazer o processamento, caso esse recurso seja 
utilizado). Nas telas Windows isso não é necessário, pois os botões ficam diretamente em 
FormProcess, sendo utilizada herança de form. Não possui métodos sobrecarregáveis como 
FormCRUD, sendo utilizados apenas eventos do presenter para interferir manualmente no 
funcionamento da tela. 
Essa classe sempre irá trabalhar em conjunto com uma classe de processo 
(MainProcess, camada model), de forma que o MAPClass deverá ser utilizado para mapear uma 
classe desse tipo. Ao utilizar o MAPClass dessa forma, será instanciado um presenter do tipo 
 Framework .NET MXM 
 
Framework .NET MXM Página 24 
 
 
padrão utilizado pela tela automaticamente (ProcessPresenterPersistence). O desenvolvedor 
poderá ainda implementar um presenter herdando de ProcessPresenterPersistence e utilizar o 
MAPPresenter para mapeá-lo, não sendo necessário utilizar o MAPClass nesse caso. 
Para maiores detalhes sobre o presenter ProcessPresenterPersistence consulte o tópico 
apropriado. 
1.4.3 FormConsult 
A classe “FormConsult” permite a implementação da camada de apresentação de telas 
de consulta. Para utilizá-la, a classe correspondente a camada de apresentação deverá herdar 
de FormConsult. Nas telas web é necessário criar botões com os nomes (ID) padrão utlizados 
pela classe FormProcess (btFilter para o botão que irá filtrar a consulta, btExcel para o botão 
que será utilizado para exportar os dados da consulta para uma planilhado Excel e btPdf para 
o botão que será utilizado para exportar os dados da consulta para um arquivo pdf). 
Essa classe sempre irá trabalhar em conjunto com uma classe de consulta 
(MainConsult, camada model), de forma que o MAPClass deverá ser utilizado para mapear uma 
classe desse tipo. Ao utilizar o MAPClass dessa forma, será instanciado um presenter do tipo 
padrão utilizado pela tela automaticamente (ConsultPresenter). O desenvolvedor poderá ainda 
implementar um presenter herdando de ConsultPresenter e utilizar o MAPPresenter para 
mapeá-lo, não sendo necessário utilizar o MAPClass nesse caso. 
Para maiores detalhes sobre o presenter ConsultPresenter consulte o tópico apropriado. 
A classe utiliza, além dos MAPs comuns às demais telas, alguns MAPs específicos 
descritos no tópico apropriado. Possui ainda dois métodos que devem ser obrigatoriamente 
implementados: 
 
Método Descrição 
ValidateFilter Deve ser utilizado para validar os dados dos 
filtros, acrescentando os erros encontrados à 
propriedade ErrorList. A consulta só será 
executada se não houverem erros na lista. 
LoadData Deverá ser implementado o carregamento 
dos dados da consulta na tela. O método 
recebe como parâmetro uma instância de 
MainConsult com todos os campos mapeados 
através de MAPControl e similares 
preenchidos. Deverá então ser feito um 
TypeCast para o tipo de classe de consulta da 
 Framework .NET MXM 
 
Framework .NET MXM Página 25 
 
 
tela e chamados os métodos para trazer os 
dados da consulta, utilizando-os para exibir a 
consulta na tela (através de databind com o 
store de uma grid, por exemplo). 
 
1.5 Classes de apresentação base 
Caso nenhuma das classes descritas anteriormente sirva para a implementação de uma 
tela específica, é possível herdar diretamente de uma das classes base, das quais todas essas 
classes herdam (elas herdam de FormMAPControl, que é o nível mais baixo de herança acima 
das classes para telas específicas). Segue descrição da função de cada classe base e de suas 
funcionalidades. Essa descrição pode ser usada como referência para as funcionalidades 
disponíveis nas classes de apresentação para telas específicas, uma vez que elas estão no 
nível mais baixo de herança. A propriedade ErrorList, por exemplo, é definida na classe base 
FormErrorList, mas é possível usá-la em FormCRUD, uma vez que FormCRUD herda de 
FormMAPControl, que herda de FormErrorList. 
1.5.1 FormBasic 
 Classe mais básica, no topo da hierarquia de classes de apresentação, implementa as 
funcionalidades comuns a todas as telas e funcionalidades específicas de cada plataforma, 
como redirecionamento para tela de login ao término da sessão na web e alteração da 
funcionalidade da tecla enter no Windows (possui a mesma função do tab, no mesmo padrão 
do Manager). 
 
1.5.1.1 Propriedades comuns a web / Windows 
 
Propriedade Descrição 
Amb, 
AmbList e 
AmbIndex 
Consulte tópico correspondente às classes Ambiente / AmbienteList 
Presenter O Presenter que irá trabalhar em conjunto com a classe de apresentação. Ao 
herdar diretamente das classes FormBasic e FormErrorList, o Presenter deverá 
ser mapeado através de MAPPresenter ou instanciado manualmente. Como em 
FormMAPControl, como será visto no tópico apropriado, é implementada uma 
série de funcionalidades que dependem de um presenter, como a auditoria por 
exemplo (a rotina de gravação de auditoria é implementada no presenter, pois 
 Framework .NET MXM 
 
Framework .NET MXM Página 26 
 
 
funciona da mesma maneira para web e para Windows), para uma classe que 
herde diretamente de FormMAPControl e não mapeie um presenter através de 
MAPPresenter será criado automaticamente um presenter básico, só com as 
funcionalidades diretamente utilizadas pela tela. Para as classes abaixo de 
FormMAPControl, existe a opção de mapear um presenter específico através de 
MAPPresenter ou utilizar apenas MAPClass, que fará com que seja instanciado 
o tipo de presenter relacionado à tela automaticamente. 
 
Propriedades web 
 
Propriedade Descrição 
AutoTrim Quando true (default) chama o trim automaticamente para todos os campos de 
texto da página quando os mesmos perdem o foco. 
 
1.5.1.2 Interface IBasicForm 
 
A interface IBasicForm é implementada pela classe FormBasic, tanto na sua versão para 
Windows quanto para web, o que permite que os presenters chamem métodos específicos de 
cada plataforma implementados nessa camada em ambas as plataformas. 
 
Método Descrição 
Clear Método para limpeza dos controles da tela. Em FormBasic este é um 
método virtual vazio, devendo ser implementado pelo desenvolvedor 
caso seja relevante para a tela que esta desenvolvendo. Em 
FormMAPControl ele é implementado, limpando automaticamente os 
controles mapeados utilizando MAPs como MAPControl e 
MAPControlKey. O parâmetro ClearKey serve para identificar se os 
campos relativos à chave primária deverão ou não ser limpos nos 
casos em que essa informação é relevante, como em FormCRUD. 
Mesmo em classes abaixo de MAPControl o desenvolvedor pode 
sobrescrever o método para interferir na limpeza dos controles, 
bastando chamar base.Clear para executar a limpeza implementada 
em FormMAPControl. 
ShowError Deve ser chamado para exibir mensagens para o usuário. Assim 
como o método Clear, em FormBasic este é um método virtual vazio, 
 Framework .NET MXM 
 
Framework .NET MXM Página 27 
 
 
sendo implementado apenas em FormErrorList. 
SetFocus Coloca o foco no campo mapeado através de MAPSetFocus. 
GetControl Retorna o controle com o nome passado como parâmetro. 
EnableMappedButton Habilita ou desabilita o botão com nome passado como parâmetro 
com base no parâmetro boolean. 
 
1.5.1.3 Métodos específicos da web 
 
Método Descrição 
SetLoading Define que um determinado DirectEvent irá exibir o loading ao ser 
executado bloqueando um outro controle. Para “em” deve-se passar o 
EventMask do DirectEvent. Para “customTarget”, o controle que será 
bloqueado enquanto o DirectEvent estiver sendo executado (passe null 
para bloquear toda a página. Para msg, passe a mensagem que será 
exibida. 
ShowNotification Mostra a mensagem passada como parâmetro como um Notification do 
Coolite. Existe uma sobrecarga em que é possível configurar a posição e 
o tamanho da notificação, e outra que espera apenas a mensagem como 
parâmetro (a notificação será exibida no centro da tela com 200px por 
200px ). 
 
1.5.1.4 Propriedades específicas da web 
 
Propriedade Descrição 
RedirectOnSessionEnd Define se deverá ser efetuado redirecionamento para a tela de login 
ao término da sessão. 
1.5.1.5 Acesso aos controles do aspx na web 
 
No FormBasic da web, no OnInit, é executada uma rotina que lê todas as propriedades 
da classe e, caso encontre controles na tela com o mesmo nome da propriedade, passa para 
essa propriedade uma instância do controle. Isso é feito para que seja possível acessar os 
controles da tela em uma classe implementada em um projeto separado do arquivo aspx, 
bastando criar nessa classe propriedades do mesmo tipo e com o mesmo nome (ID) do 
controle na tela. Dessa forma, conforme descrito anteriormente, é possível manter no website 
apenas os aspx, sem nenhum código implementado no cs. 
 Framework .NET MXM 
 
Framework .NET MXM Página 28 
 
 
1.5.2 FormErrorList 
Herda de FormBasic, acrescentando uma propriedade do tipo ErrorList, e implementa o 
método ShowError, que pode ser chamado em qualquer classe que herde de FormErrorList 
para mostrar na tela as mensagens contidas nessa ErrorList para o usuário. Para maiores 
informações sobrea classe ErrorList consulte o tópico apropriado. 
 
1.5.2.1 Interface ICustomError 
 
Propriedade Descrição 
ErrorList Propriedade do tipo ErrorList 
 
1.5.3 FormMAPControl 
 
Implementa toda a parte automatizada da tela através do uso de MAPControl e similares, 
como MAPControlKey, MAPGridControl, etc. Para ser capaz de usar qualquer MAP relacionado 
aos controles da tela o desenvolvedor deverá herdar desta classe. É também a partir dessa 
classe que é implementada a auditoria. 
1.5.3.1 Interface IMAPControl 
 
A interface IMAPControl é implementada pela classe FormMAPControl, tanto na sua 
versão para Windows quanto para web, o que permite que os presenters chamem métodos 
específicos de cada plataforma implementados nessa camada em ambas as plataformas. Esses 
métodos / propriedades na prática são utilizados apenas internamente pelos presenters, 
havendo pouca utilidade em seu uso direto pelo desenvolvedor. 
 
1.5.3.1.1 Propriedades 
 
Propriedade Descrição 
MAPControls Lista de todos os controles mapeados na tela através de 
MAPControl e similares. 
 
1.5.3.1.2 Métodos 
 
Método Descrição 
GetControl Busca o controle com o nome passado como 
parâmetro na tela. 
 Framework .NET MXM 
 
Framework .NET MXM Página 29 
 
 
GetMAPControl Busca o controle com o nome passado como 
parâmentro em todos os controles mapeados. 
ClearControl Limpa o valor de um controle (p. ex. colocando o 
texto de um textbox em branco ou desmarcando 
um checkbox). 
GetValueFromControl Retorna o valor do controle passado como 
parâmetro. 
SetValueInControl Insere o valor passado para o parâmetro value no 
controle cujo nome foi passado para o parâmetro 
controlName para exibição na tela. 
Click Em FormMAPControl é um método virtual em 
branco. É implementado nos presenters que 
herdam de FormMAPControl, associando ao 
evento de clique de um dos botões da tela o 
EventHandler passado para o parâmetro Click. O 
parâmetro TypeButton é utilizado para saber em 
qual botão o evento deve ser associado. Isso 
permite que a rotina que será executada ao clicar 
no botão fique implementada no presenter. 
EnableButton Em FormMAPControl é um método virtual em 
branco. É implementado nos presenters que 
herdam de FormMAPControl, habilitando ou não 
(parâmetro value) um controle da tela, caso o 
usuário possua ou não acesso à propriedade 
associada a esse controle. O parâmetro 
TypeButton é utilizado para saber em qual botão 
o evento deve ser associado. 
GetControlIdentificationPropertyName Retorna o nome da propriedade dos controles 
utilizada para identificá-los em cada plataforma 
(ID na web e Name no Windows). 
IsGridControl* Retorna um valor boolean identificando se um 
controle é uma grid ou não. 
GetDataFromGrid* Retorna as informações contidas numa grid como 
um DataTable 
SetValueInGridControl* Semelhante a SetValueInControl para grids. 
SetupGridDescription Associa evento ao sair de um campo com um 
 Framework .NET MXM 
 
Framework .NET MXM Página 30 
 
 
código em uma grid para carregar a descrição em 
outro campo. 
SetHelpWindowInControl Associa o helpwindow a um controle. 
SetHelpWindowInGridColumn* Semelhante a SetHelpWindowInControl, para 
uma coluna de uma grid. 
LoadListControl* Utilizado para preencher um controle mapeado 
com MAPListControl com os valores de seu Enum. 
LosdLidtInGridControl* Semelhante a LoadListControl, para uma coluna 
de uma grid. 
AssociateValidationToControl Associa uma validação criada através de 
MAPControlValidation a um controle. 
SetDescriptionInControl Em dois controles código / descrição, associa o 
controle com a descrição ao controle com o 
código. 
GetClickEventParameters Passa o EventArgs do clique de um botão. 
SetControlInProperty Insere o controle numa propriedade da classe 
com o mesmo nome do controle. 
 
* Implementados apenas no Windows. 
1.6 Controles / Componentes 
1.6.1 Web (Ext.Net.MXMControls) 
Os componentes para web pertencem ao assembly Ext.Net.MXMControls. 
1.6.1.1 Help 
 
1.6.1.1.1 HelpField 
 
Campos que possuem uma consulta associada. Esses campos estão sempre associados a 
uma tabela do banco de dados, e exibem um botão com um desenho de uma lupa ao lado do 
campo de texto que quando clicado exibe uma tela de consulta em que o usuário pode buscar 
e selecionar um dos valores disponíveis para inserção no campo. A configuração dessas telas 
de consulta é feita através de classes que herdam de MainHelpConfig. Consulte o tópico 
relacionado à classe MainHelpConfig para descrição de como implementar classes desse tipo. 
Todas as propriedades utilizadas no TextField do Coolite (FieldLabel, etc) podem ser utilizadas 
em controles desse tipo. 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 31 
 
 
Propriedade Descrição 
HelpClass O nome da classe MainHelpConfig associada ao controle (utilize a 
propriedade AssemblyQualifiedName, p.ex. 
MinhaClasseDeAjuda.GetType().AssemblyQualifiedName). Existem 
parâmetros dos MAPs MAPControl, MAPControlKey, etc, para fazer essa 
associação, de forma que normalmente não é necessário utilizar essa 
propriedade explicitamente. 
HelpIndex Utilize para definir o valor da propriedade Index da classe 
MainHelpConfig que será utilizado. 
DescriptionFieldID Caso o HelpField seja utilizado em um campo código / descrição, defina 
o ID do campo que receberá a descrição relacionada ao código inserido 
no campo. 
 
Habilitando tecla F1: 
 Devido a uma série de fatores (W3C, dificuldade de compatibilidade entre browsers, 
etc) o HelpField por padrão não funciona como no Manager, em que a janela de busca é 
exibida ao pressionar a tecla “F1”. Porém, como esse comportamento pode ser necessário 
para alguns clientes, a tecla F1 pode ser habilitada apenas para o Internet Explorer através do 
web.config. Para isso, adicione a tag <add key="enableF1" value="true"/> ao AppSettings. 
1.6.1.1.2 HelpParameter 
 
HelpParameter não é um componente, é uma classe que pertence a Ext.Net.MXMControls 
utilizada pelo HelpField para associar os parâmetros da classe MainHelpConfig (consulte trecho 
sobre a propriedade Where no tópico relacionado à classe MainHelpConfig) a controles da tela 
ou definir valores para os parâmetros. Devem ser adicionadas instâncias dessa classe à 
propriedade parameters do HelpField para cada parâmetro utilizado na propriedade Where da 
classe MainHelpConfig associada ao controle. A classe possui as seguintes propriedades: 
 
Propriedade Descrição 
Name Nome do parâmetro como aparece na propriedade Where da classe 
MainHelpConfig, sem o “:”. 
IsControlValue Define se o valor virá de um controle da tela (true) ou será definido 
explicitamente pelo desenvolvedor. 
Value Caso o valor seja buscado de um controle da tela, essa propriedade 
deverá conter o ID do controle. Caso contrário, deve ser passado o 
 Framework .NET MXM 
 
Framework .NET MXM Página 32 
 
 
valor do parâmetro para essa propriedade. 
 
1.6.1.2 Campos de texto 
 
1.6.1.2.1 MXMNumberField 
 
Permite apenas a digitação de números, conforme as regras definidas através das 
propriedades do componente. Herda de Ext.Net.NumberField do Coolite, possuindo todas as 
propriedades desse componente, como FieldLabel, etc. 
 
Propriedade Descrição 
ShowSeparator Define se deve ser exibido separador de milhar ao sair do campo. 
AlignLeft Por padrão os campos numéricos são alinhados à direita. Caso deseje 
que sejam alinhados à esquerda, utilize esse campo (true). 
DecimalPrecision Número de casas decimais. 
AllowNegative Define se o campo permite a digitação de valores negativos.AllowDecimals Define se o campo permite a digitação de números com decimais. 
MXMDisabled Quando true, desabilita o controle com a mesma aparência utilizada 
pelos campos descrição do HelpField. 
 
1.6.1.2.2 MXMDateField 
 
Permite apenas a digitação de datas, conforme as regras definidas através das 
propriedades do componente, e formata qualquer valor numérico digitado como uma data 
válida ao sair do campo. Herda de Ext.Net.DateField do Coolite, possuindo todas as 
propriedades desse componente, como FieldLabel, etc. 
 
Propriedade Descrição 
IsLongYear Quando true o campo adotará o padrão de data com ano 4 dígitos 
(dd/mm/yyyy). Quando false o de 2 dígitos (dd/mm/yy). 
MXMDisabled Quando true, desabilita o controle com a mesma aparência utilizada 
pelos campos descrição do HelpField. 
 
 
1.6.1.2.3 MXMMonthYearField 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 33 
 
 
Permite apenas a digitação de valores no formato mês/ano e formata qualquer valor 
numérico digitado nesse formato. Herda de Ext.Net.TextField do Coolite, possuindo todas as 
propriedades desse componente, como FieldLabel, etc. 
 
1.6.1.2.4 MXMTimeField 
 
Permite apenas a digitação de horas no formato HH24:MM e formata qualquer valor 
numérico digitado nesse formato. Herda de Ext.Net.TextField do Coolite, possuindo todas as 
propriedades desse componente, como FieldLabel, etc. 
1.6.1.3 Métodos de extensão 
 
No Assembly Ext.Net.MXMControls estão implementados métodos de extensão 
relacionados a controles. Para usá-los, basta fazer referência ao assembly (using). 
 
Método Descrição Controles suportados 
SetMXMDisabled Desabilita o controle com aparência 
semelhante à do campo descrição do 
Help Field. 
HelpField, TextField, TriggerField, 
TextArea, ComboBox 
 
1.6.2 Windows 
 
Os componentes para Windows pertencem ao assembly MXM.Controls. 
1.6.3 Windows (MXM.Controls) 
1.6.3.1.1 MXMTextBox 
 
O MXMTextBox permite a utilização de janelas de consulta ao ser associado a uma classe 
MainHelpConfig (semelhante so HelpField da web, porém a exibição da janela de ajuda é feita 
através das teclas F1 ou F4, não possui botão para chamar a janela ajuda). Permite ainda 
controlar a entrada de dados (por exemplo, permitindo apenas entrada de valores numéricos, 
data, etc). 
 
Propriedade Descrição 
ControleDescricao Caso o MXMTextBox seja utilizado em um campo código / descrição, 
defina o TextBox que receberá a descrição relacionada ao código 
inserido no campo. 
 Framework .NET MXM 
 
Framework .NET MXM Página 34 
 
 
WindowHelp A classe MainHelpConfig associada ao controle (passar instância da 
classe). Existem parâmetros dos MAPs MAPControl, MAPControlKey, etc, 
para fazer essa associação, de forma que normalmente não é necessário 
utilizar essa propriedade explicitamente. 
HelpFilter Deverá ser passada uma lista dos controles que serão usados como 
parâmetros na ordem em que aparecem na propriedade Where. 
DataType Utilizado para controlar o tipo de dados que podem ser inseridos no 
controle. Os tipos disponíveis são os seguintes (enum : 
Tipo Descrição 
Text Default, permite digitação de qualquer caracter. 
Number Permite apenas a digitação de números, com ou 
sem casas decimais, com e sem sinal. 
UnsignedNumber Permite apenas a digitação de números, com ou 
sem casas decimais, sem sinal. 
Integer Permite apenas a digitação de números inteiros, 
com ou sem sinal. 
UnsignedInteger Permite apenas a digitação de números inteiros 
sem sinal. 
DayMonthYear Para datas com 4 dígitos no ano (dd/mm/yyyy). 
MonthYear Para campos com valor mês/ano (mm/yyyy). 
DayMonthShortYear Para datas com 4 dígitos no ano (dd/mm/yy). 
ShortTime Para horas (hh24:mm). 
IntegerCode Para digitação de códigos numéricos 
(sequences, etc). 
CharCase Se o campo aceita apenas letras maiúsculas (UpperCase), minúsculas 
(LowerCase) ou ambos os tipos (Normal), que é o valor default. Valores 
do enum CharCaseList. 
Digits Quantidade de dígitos decimais, caso o DataType seja Number ou 
UnsignedNumber. 
 
1.6.3.1.2 MXMDataGridView 
 
DataGridView no padrão da MXM (Enter funciona igual ao Tab para passar o foco para a 
próxima coluna, Ctrl + Delete exclui a linha, etc). 
 Framework .NET MXM 
 
Framework .NET MXM Página 35 
 
 
1.6.3.1.3 DataGridViewMXMTextBoxColumn / DataGridViewMXMTextBoxCell 
 
Permitem criar uma coluna no DataGridView que funciona como um MXMTextBox, com 
F1, etc. 
1.6.4 Web (Ext.Net.MxmControls) 
 
3. A camada presenter 
 
 
 Os presenters fazem parte dos assemblies MXM.Presenter e MXM.Presenter.Persistence. 
Em MXM.Presenter estão os presenters base, sem nenhum tipo de vínculo com o 
MXM.Persistence. O projeto MXM.Presenter.Persistence possui presenters herdando desses 
presenters base e implementando tudo que utiliza MXM.Persistence. 
1.6.5 MainPresenter 
 
Presenter mais básico. Todos os demais presenters, com exceção dos de login, herdam 
desse presenter. Define a propriedade View, que é um objeto que corresponde à camada de 
apresentação necessário para o funcionamento de todos os presenters que irão herdar de 
MainPresenter. É através dessa propriedade que os presenters chamam métodos na camada 
de apresentação: cada tipo de classe da camada de apresentação implementa interfaces 
 Framework .NET MXM 
 
Framework .NET MXM Página 36 
 
 
próprias (p. ex. tanto a classe FormMAPControl do Windows quanto a da web implementam a 
interface IMAPControl), o que permite ao presenter chamar métodos em comum nessas 
classes. Dessa forma, determinadas rotinas, que funcionam de maneira comum, independente 
da plataforma, podem ser implementadas na camada presenter, sendo feitas chamadas de 
métodos nas classes da camada de apresentação para executar as tarefas específicas de cada 
plataforma, como bloquear um botão ou ler o valor de um campo da tela. 
 
1.6.6 MAPControlPresenter 
 
Implementa a gravação da auditoria de acesso às telas e toda parte independente de 
plataforma das rotinas relacionadas ao uso de MAPControl e similares para mapear controles 
da tela para a camada model. A partir desse presenter é necessária interação com o banco (no 
caso desse presenter apenas para gravar a auditoria), de forma que nele é definida a 
propriedade abstrata DBControl, do tipo IDBPresenterControl, que será utilizada para interação 
com o banco (consulte tópico sobre a interface IDBPresenterControl) e o método abstrato 
InstantiateDbControl, onde essa propriedade deverá ser instanciada. Todos os presenters que 
herdarem de FormMAPControl deverão implementar essa propriedade / método (no caso dos 
presenters contidos em MXM.Presenter.Persistence utilizando a classe PersistControl, que 
implementa a interface IDBPresenterControl utilizando MXM.Persistence). 
 
1.7 Presenters associados a tipos específicos de telas 
 
Conforme descrito no tópico relativo à camada de apresentação, cada uma das classes de 
apresentação para telas específicas possui um presenter padrão associado. Estes presenters 
estão em MXM.Presenter.Persistence e herdam de presenters base que estão no assembly 
MXM.Presenter. Segue descrição desses presenters e das interfaces que implementam. Essas 
interfaces podem ser usadas na camada de apresentação para, através da propriedade 
“Presenter”, utilizar os eventos dos presenters para interferir no funcionamento das telas. 
Definem ainda métodos que são utilizados na camada de apresentação para chamar métodos 
nos presenters. 
1.7.1 Presenters CustomCRUDPresenter e CRUDPresenter 
 
CustomCrudPresenter implementa a interface ICustomCRUDPresenter, e faz parte do 
assembly MXM.Presenter.Serve de base para o presenter CRUDPresenter, que implementa a 
interface ICRUDPresenter e faz parte do assembly MXM.Presenter.Persistence. CRUDPresenter 
é o presenter padrão de telas CRUD. 
 Framework .NET MXM 
 
Framework .NET MXM Página 37 
 
 
1.7.1.1 Interface ICustomCRUDPresenter 
 
1.7.1.1.1 Eventos 
 
Evento Descrição 
BeforeGetRecord Disparado quando o usuário pressiona o botão para 
executar uma operação na tela (save, update ou delete), 
antes da montagem da lista de objetos que serão 
persistidos, antes da chamada ao método 
GetRecordInControl da camada e apresentação. O 
parâmetro ExecuteOperation pode ser usado para definir se 
a operação será ou não executada. 
AfterGetRecord Disparado quando o usuário pressiona o botão para 
executar uma operação na tela (save, update ou delete), 
após a montagem da lista de objetos que serão persistidos. 
O parâmetro ExecuteOperation pode ser usado para definir 
se a operação será ou não executada. È passada também a 
lista de objetos como parâmetro. 
BeforeCommit Disparado quando o usuário pressiona o botão para 
executar uma operação na tela (save, update ou delete), 
antes de executar o commit; 
AfterCommit Disparado quando o usuário pressiona o botão para 
executar uma operação na tela (save, update ou delete), 
após executar o commit; 
BeforeDoOperation Disparado quando o usuário pressiona o botão para 
executar uma operação na tela (save, update ou delete), 
após a validação, caso a mesma não retorne erros, e antes 
da operação ser executada, para cada objeto de 
persistência da lista. 
BeforeLoadViewFromRecord Executado ao sair do campo contendo a PK em que serão 
carregados os dados na tela antes de carregar os dados na 
tela, antes do SetRecordInControl da camada de 
apresentação. Recebe como parâmetro o objeto já com as 
PKs carregadas. 
AfterLoadViewFromRecord Semelhante ao BeforeLoadViewFromRecord, executado 
após a tela ser carregada. 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 38 
 
 
1.7.1.1.2 Métodos 
 
Método Descrição 
KeyExit Carrega a tela com os dados do objeto correspondente a 
um registro da tabela que contenha as pks iguais aos 
campos de pk preenchidos na tela. 
 
1.7.1.2 Interface ICRUDPresenter 
 
1.7.1.2.1 Eventos 
 
Evento Descrição 
AfterGetRecordInControl Executado para cada objeto que for criado a partir da 
propriedade CountSaveRecord (por padrão 1 objeto), após 
a criação do objeto. É passada a lista com os objetos 
adicionados até o momento em que o objeto foi 
adicionado e a posição do objeto na lista. 
BeforeDoPersistenceOperation Semelhante a BeforeDoOperation da 
ICustomCRUDPresenter, mas passando além da classe que 
será persistida um persist com a conexão aberta. 
AfterDoPersistenceOperation Semelhante a BeforeDoPersistenceOperation, mas 
executado após a execução da operação. 
 
1.7.1.2.2 Propriedades 
 
Propriedade Descrição 
CountSaveRecord Usado para definir quantos objetos serão criados 
automaticamente com os dados dos campos mapeados na 
tela na lista de objetos que serão persistidos. Por padrão 
essa propriedade tem o valor 1, podendo ser alterada em 
telas que salvam mais de um item de uma vez. 
1.7.2 Presenters CustomProcessPresenter e ProcessPresenterPersistence 
 
CustomProcessPresenter serve de base para o presenter ProcessPresenterPersistence, 
que implementa a interface IProcessPresenter e faz parte do assembly 
MXM.Presenter.Persistence. ProcessPresenterPersistence é o presenter padrão de telas de 
processo. 
 Framework .NET MXM 
 
Framework .NET MXM Página 39 
 
 
 
1.7.2.1 Interface IProcessPresenter 
 
1.7.2.1.1 Eventos 
 
Evento Descrição 
BeforeProcess Disparado ao pressionar o botão para processar ou desfazer 
processamento, antes de executar o processo. Recebe como 
parâmetros uma instância da classe de processo e 
TypeExecProcess, que identifica qual botão foi pressionado. 
AfterProcess Disparado após o processamento, após o commit do 
persistence, de forma que só será disparado se o processo for 
executado sem erros (ErrorList). Mesmos parâmetros do 
BeforeProcess. 
 
1.7.3 Presenters CustomConsultPresenter e ConsultPresenter 
 
CustomConsultPresenter implementa a interface ICustomConsultPresenter, e faz parte do 
assembly MXM.Presenter. Serve de base para o presenter ConsultPresenter, que faz parte do 
assembly MXM.Presenter.Persistence e é o presenter padrão de telas de consulta. 
 
1.7.3.1 Interface ICustomConsultPresenter 
 
1.7.3.1.1 Métodos 
 
Método Descrição 
Filter Este é o método que é executado ao pressionar o botão de 
filtragem da consulta. Pode ser chamado em uma tela de 
consulta caso a consulta precise ser feita fora do clique do 
botão (por exemplo em uma tela em que a consulta já tenha 
que vir carregada ao ser aberta, esse método pode ser 
chamado no PageLoad). 
 
1.7.4 Interface IDBPresenterControl / Classe PersistControl 
 
Como os presenters base definidos em MXM.Presenter não possuem vínculo com a 
Persistence, sua interação com o banco de dados é feita através da interface 
 Framework .NET MXM 
 
Framework .NET MXM Página 40 
 
 
IDBPresenterControl, que define métodos de interação com o banco, como abrir e fechar a 
conexão, etc. Essa interface é implementada utilizando o MXM.Persistence para executar essa 
interação com o banco em MXM.Presenter.Persistence pela classe PersistControl. 
 
Métodos da interface IDBPresenterControl 
 
Método Descrição 
Open Abre conexão com o banco 
Close Fecha conexão com o banco 
StartTransaction Inicia transação 
InTransaction Retorna bool indicando se está na transação ou se a mesma já 
foi encerrada 
Commit Executa commit 
RollBack Executa rollback 
GetRecord Traz um registro do banco utilizando o objeto passado como 
parâmetro como filtro 
GetRecords Retorna lista com todos os registros da tabela relacionada ao 
tipo de objeto passado para o parâmetro clazz. 
GetListRecordType Retorna o tipo dos objetos de uma lista (propertyName) 
mapeada em um objeto (Record). 
SaveAudit Salva a auditoria de acesso à tela relacionada ao ID de função 
passado como parâmetro para IDFuncion com base nos dados 
do ambiente passado para Amb (p. ex. o usuário gravado será 
Amb.UserName). 
SaveDocumentAudit Salva a auditoria de acesso ao documento cujo código foi 
passado como parâmetro para IDDocument com base nos 
dados do ambiente passado para Amb (p. ex. o usuário 
gravado será Amb.UserName). 
 
 
 Framework .NET MXM 
 
Framework .NET MXM Página 41 
 
 
4. A camada Model 
 
1.8 Classes de Persistência 
As classes de persistência estão diretamente associadas a uma tabela no banco, sendo 
cada coluna da tabela associada a uma propriedade pública da classe. O mapeamento é feito 
diretamente na classe, no próprio arquivo .cs, utilizando attributes semelhantes aos MAPs. 
Estes attributes, posicionados em locais específicos na classe, permitem informar à camada de 
persistência todos os dados relacionados ao mapeamento classe-tabela, como o nome da 
tabela a que uma classe está relacionada, o nome de cada coluna a que cada propriedade está 
relacionada, se uma determinada coluna está associada a uma coluna que representa uma 
chave primária ou estrangeira, etc. 
 
1.8.1 Mapeando classes 
 
1.8.1.1 Regras Gerais 
 
• Constructors: As classes deverão ter sempre um constructor sem parâmetros, e, para 
conveniência de uso, um constructor recebendo como parâmetro as chaves primárias. 
• Herança: As classes de persistência em geral deverão herdar de 
"MainRecordPesistence", exceto