Guia do Programador. Versão /5/2005

Transcrição

1 Versão /5/2005 Guia do Programador Tecnologia de Informação Av. ACM, Ed. Fernandez Plaza, 22º andar Cidadela, Salvador - BA CEP: Tel: (71) FAX: (71)

2 INDICE Objetivo...3 A quem se destina?...3 Pré-Requisitos...3 O que há de novo? UniFw.Net Objetivo Projeto básico das aplicações.net com o UNIFW Camada de apresentação Camada de negócio Camada de dados Sequência básica de execução Implementando a camada de Dados e/ou Negócio UniComponent Interface IDataBase ResultSets através de Stored Procedures no OracleDatabase e OracleDatabaseTM Acesso a dados com UniCommand UniComponentBSDB Auditoria Transaction Manager (TM) Integração com Workflow Tratamento de Erros Implementando a camada de apresentação Introdução Projeto da Camada de Apresentação ASPX x ASCX A Classe Unitech.Web.FWPage A Classe Unitech.Web.Template A Classe Unitech.Web.Frame O processo de desenvolvimento de telas Usando o BookMark Redirecionamento de Páginas Componentes Visuais Dicionário Ajuda Log e Tratamento de Erros Configuração do Ambiente/Componentes WebConfig Página inicial Página de autenticação (login) Tópicos Avançados Envio de s Informações sobre o usuário autenticado Ciclo de vida de uma Página ASP.NET Utilização do GAC Inspetores WEB Autenticadores Serviços Tracer Add-Ins do Visual Studio.NET Preparação do Ambiente de Desenvolvimento do UNIFW.NET Softwares Básicos e Ambiente Passos para preparação do ambiente F.A.Q Bibliografia...68 Pág.:2

3 Objetivo Este documento tem como objetivo servir de referência rápida para desenvolvedores que pretendem utilizar os recursos do UniFW.Net para desenvolver suas aplicações. Através deste documento, pode-se obter tanto uma visão geral sobre o funcionamento e programação com o UniFW.Net, quanto às formas de utilização de diversos dos seus componentes. A quem se destina? Desenvolvedores que procuram conhecer ou lembrar, da correta utilização de um determinado componente ou funcionalidade existente no UniFW.Net versão 1.6. Pode ser utilizado também por desenvolvedores que pretendem aprender a utilizar um novo recurso disponibilizado pelo mesmo e que podem ser utilizados no desenvolvimento de novas aplicações ou funcionalidades. Pré-Requisitos Fluência no desenvolvimento de aplicações WEB na plataforma MS.NET Fluência nas linguagens VB.NET ou C#. Fluência na linguagem DDL e TransactSQL no MS SQLServer O que há de novo? Documentação dos novos componentes visuais UniBusinessBox, UniDateBox e UniNumberBox na sessão Documentação das alterações no componente visual UniTextBox na sessão Inclusão da seção Add-Ins do Visual Studio.NET Inclusão da sessão UniComponentBSDB Pág.:3

4 1. UniFw.Net 1.1. Objetivo Este documento tem como objetivo fornecer informações essenciais aos desenvolvedores de páginas ASPX e controles ASCX que utilizem o framework Unifw para este fim Projeto básico das aplicações.net com o UNIFW O Unifw (Unitech Framework WEB) é um framework para desenvolvimento de aplicações WEB para a plataforma.net 1.1 da Microsoft, desenvolvido pela Unitech. Composto por diversos módulos, o UNIFW fornece ao desenvolvedor soluções prontas para serem reutilizadas e especializadas para novas aplicações em fase de projeto, ou implementação. O diagrama abaixo demonstra a arquitetura básica do Unifw: Aplicação X WebControls UNIFW Inspetores Web Workflow Segurança Auditoria Conteúdo Serviço Ajuda Sequenciador Dicionário Validators Serviços De acordo com o diagrama acima, diferente de uma simples biblioteca de componentes, o framework UNIFW representa o núcleo da aplicação desenvolvida. É ele quem possui os principais algoritmos e estruturas normalmente utilizadas pelas aplicações WEB feitas na plataforma.net, assim como os ganchos utilizados para se integrar e especializar seu comportamento básico. O UNIFW é composto dos seguintes módulos: Web: representado pelo assembly Unitech.Web. Possui estruturas que possibilitam o controle de execução das páginas, tais como FWPage, Templates e Frames. Além disso, esse módulo possui uma biblioteca de componentes para composição de telas WEB através de ASPXs/ASCXs. Essa biblioteca possui classes que representam componentes visuais HTML tais como UniTextBox, UniDataGrid, UniTreeView, UniDropDownList e outras mais, que herdam de componentes já existentes no Framework.NET Microsoft. Segurança: representado pelo assembly Unitech.UNIFW.Seguranca. Possui as estruturas para configuração das políticas de segurança, tais como domínios, usuários, papeis e grupos de trabalho. Workflow: representado pelo assembly Unitech.UNIFW.Workflow. Módulo com as estruturas de controle e configuração de aplicações que utilizam Workflow, tais como fluxos, transições, entidades de fluxo e solicitações de transição. Pág.:4

5 Auditoria: representado pelo assembly Unitech.UNIFW.Auditoria. Possui as estruturas para implementação da auditoria de operações nas aplicações. Serviço: representado pelo assembly Unitech.UNIFW.Servico. Possui as estruturas para implementação de serviços assíncronos executados pelas aplicações. Com elas, pode-se implementar classes que representam serviços que serão executados em intervalos previamente configurados no framework. Ajuda: representado pelo assembly Unitech.UNIFW.Ajuda. Estrutura para implementação de Help integrado à aplicação. Ou seja, pode-se cadastrar os tópicos associados às telas e, em tempo de execução, montar a página de help de acordo com a configuração feita. Conteúdo: representado pelo assembly Unitech.UNIFW.Conteúdo. Possui as estruturas para gerência de notícias e banners a serem disponibilizadas pela aplicação. Dicionário: representado pelo assembly Unitech.UNIFW.Dicionário. Possui as estruturas para gerência de Mensagens e Textos dicionarizados. Pode-se cadastrar Textos para os controles visuais, ou mensagens de erros das páginas em diversos idiomas, e conforme a configuração da aplicação, o Framework se encarregará de mostrar o texto no idioma correto. Voltado para o aumento da produtividade no desenvolvimento de aplicações WEB, na plataforma.net, o projeto do Unifw é feito para melhor se encaixar na estrutura de aplicações em 3 camadas: apresentação, negócio e dados, normalmente utilizadas para este fim. Para cada camada o Unifw fornece a infra-estrutura necessária para seu correto projeto e controle de execução, possibilitando ao projetista e desenvolvedor uma maior chance de sucesso em seu desenvolvimento. È importante lembrar que o Unifw.NET é um framework criado sobre o Framework.Net Microsoft, portanto parte deste pôde ser reaproveitada e especializada, tal como os componentes visuais e componentes validators Camada de apresentação A camada de apresentação tem como objetivo fornecer ao usuário todas as funcionalidades existentes na aplicação. Baseada na linguagem HTML e Javascript, as interfaces de aplicações WEB são construídas em tempo de execução no servidor WEB associado. Na plataforma.net há uma separação visível entre o layout da página (HTML ASPX/ASCX) e seu código de execução (CodeBehind). Estes componentes devem ser combinados de forma a manter as seguintes características: Limpeza de codificação: páginas ASPX/ASCX não devem conter códigos embutidos, apesar de poderem ter, assim como seu CodeBehind não serve para montar páginas HTML. Reutilização de código: é desejável que se possa reutilizar código de montagem de páginas, tais bcomo lógica de validação de campos e seqüência básica de execução de telas semelhantes. Transparência de controle: funcionalidades de controle tais como segurança e auditoria devem ser aplicadas de forma transparente aos componentes implementados. Para esta camada, o Unifw fornece componentes que possibilitam o controle desde o recebimento da requisição HTTP, à montagem da página solicitada. Neste documento, serão discutidas as principais estruturas e componentes envolvidos com o controle de execução da camada de apresentação, que serão devidamente detalhados mais adiante. Pág.:5

6 1.4. Camada de negócio A camada de negócio tem como objetivo fornecer à aplicação todas as funcionalidades de controle da lógica de negócio da aplicação. É nesta camada que estão representadas as entidades e processos envolvidos com as funcionalidades disponibilizadas pela camada de apresentação. Todas as regras de validação, controle de processos e integridade lógica dos dados são devidamente implementados nesta camada. Fazem parte desta camada componentes que se utilizam de Transações, DataSets e etc. Um bom projeto e implementação de componentes da camada de negócio deve possibilitar as seguintes características: Independência da camada de apresentação: componentes de negócio devem poder ser utilizados por componentes da camada de interface de forma independente. Ou seja, componentes de negócio não podem fazer referência a componentes da camada de interface, pois se criará um acoplamento indesejado. Performance adequada: a depender do tipo de solução a ser implementada, uma diferente estrutura de programação deve ser utilizada para atender ao requisito levantado. Flexibilidade de configuração: mudanças previstas de comportamento devem ser disponibilizadas sem a necessidade de reprogramação de componentes. Isto só é possível com um projeto de baixo acoplamento entre componentes estratégicos. O framework Unifw fornece a classe Unitech.Component.UniComponent para apoio ao desenvolvimento da camada de negócio Camada de dados A plataforma.net não dispõe atualmente de recursos de persistência automática em banco de dados, portanto se faz necessário o acesso ao mesmo através de objetos ADO.NET para atualização ou apenas consulta dos dados existentes. Um projeto de componentes da camada de dados deve possuir as seguintes características: 1. Independência da camada de negócio: componentes da camada de dados não devem fazer referência à estruturas da camada de negócio. 2. Desacoplamento e Flexibilidade: em muitos casos ocorrem mudanças do banco de dados que se está utilizando para o acesso. Nestes casos se faz necessária a implementação de novas classes de acesso a banco de dados (utilizando o ADO.NET) que o façam da maneira adequada para o novo banco de dados utilizado. Com isso, se faz necessária a implementação de uma estrutura que possibilite a mudança dos componentes de acesso a dados sem que isto implique em qualquer impacto para classes de negócio que os utilizem. O Unifw disponibiliza componentes que auxiliam a implementação de componentes de acesso a base de dados de diversos tipos. Componentes como Classes Unitech.Component.UniComponent, Unitech.Data, fornecem funcionalidades prontas de abertura de conexão, conversão de resultados de Stored Procedures em DataSets, formatação de dados SQL. Os detalhes sobre a implementação dos componentes da camada de dados com o Unifw serão detalhados mais adiante. Pág.:6

7 1.6. Sequência básica de execução Aplicações projetadas para utilizar as estruturas do Unifw possuem em comum uma sequência básica de execução. Esta sequência se inicia no recebimento da requisição HTTP e finaliza com o término do processamento da página solicitada. O diagrama abaixo exibe os principais passos envolvidos no processamento das requisições recebidas: Browser FWPage Inspetor Template Arq. ASCX Classes BS Classes DB BD HTTP ValidaSeguranca MontaPagina Load exec negócio exec. dados persistir No diagrama anterior, é exibida a sequência básica de execução de uma típica aplicação WEB que se utiliza do Unifw. Seguem as descrições dos principais componentes envolvidos: Browser: aplicação cliente WEB. É ele que exibe a interface ao usuário e cria as novas requisições HTTP que serão enviadas ao servidor. Estas requisições contém informações que indicam qual tela, ação e parâmetros da solicitação. FWPage: componente integrante do Unifw, que centraliza o recebimento das requisições HTTP enviadas pelos clientes. Cabe a este componente efetuar as validações e encaminhar o processamento das requisições recebidas. Este encaminhamento pode ser resumido na verificação de segurança(inspetor) e carregamento do arquivo de Template. Inspetor: cabe ao inspetor, efetuar todas as validações e verificações necessárias para se autenticar e autorizar o usuário que enviou a requisição. Além disso, efetua os registros de auditoria, conforme configurado. Template: cabe ao template identificar quais arquivos (.ASCX) que deverão ser carregados nos quadros do template da tela requisitada. Arq.ASCX: implementação de um arquivo ASCX que constrói a interface HTML que será exibida para o cliente, normalmente composta por tabelas, campos de entrada de dados e javascripts. Cabe a esta implementação apenas a formatação adequada do resultado da solicitação feita. Qualquer implementação mais complexa, que envolva chamada de componentes de negócio, condições ou laços, devem ser feitas no CodeBehind deste ASCX que fará o processamento necessário. Classes BS: implementação da camada de negócio da aplicação. São classes implementam todas as rotinas de validação e processamento necessárias para a operação e integridade das informações mantidas. Classes DB: implementação da camada de dados da aplicação. São classes que implementam consultas e execuções no banco. BD: banco de dados utilizado. Contém as tabelas com os dados das entidades utilizadas na aplicação. A depender do projeto, pode ainda conter procedures. A descrição detalhada de implementação de cada componente e dos recursos do Unifw existentes para cada situação será devidamente feita nas próximas sessões deste documento. Pág.:7

8 2. Implementando a camada de Dados e/ou Negócio A camada de dados e negócio é composta por um conjuto de classes cujo principal objetivo é, respectivamente, acessar uma determinada base de dados e tratar das regras de negócio. Porém o Unifw não exige que os projetos tenham esta divisão. Sugere-se que as classes que visam acessar a dados e/ou tratar das regras de negócio herdem de Unitech.Component.UniComponent, sendo a sua utilização decisão de projeto. Na sessão a seguir será detalhada as funcionalidades e facilidades que a classe UniComponent proporciona UniComponent O Unitech.Component.UniComponent foi criado com o intuito de fornecer um conjunto de funcionalidades prontas para as classes que o estendem. Basicamente, o UniComponent fornece funcionalidades de acesso a banco de dados, geração de seqüências e tratamento de erros que podem ser reutilizadas e estendidas pelos demais componentes. A figura abaixo apresenta a estrutura do UniComponent. Segue um exemplo de código de um componente que se utiliza do UniComponent: 1. Public Class Template 2. Inherits UniComponent 3. Public Sub New() 4. SiglaDataSource = "sigla_do_data_source" 5. End Sub 6. Function Inserir(ByRef DS As DataSet) As Int32 Implements BS.ITemplate.Inserir 7. Dim Retorno As Int32 8. Dim SGBD As Unitech.Data.IDatabase = CreateDataBaseInstance( minhaorigemdados ) 9. DS.Tables(0).Rows(0)("Identificador") = GetNewNumber( minhasequencia ) 10. Retorno = SGBD.SPExecute("SEGURTemplateINS", SGBD.FillParameters("SEGURTemplateINS", DS.Tables(0).Rows(0))) 11. Return Retorno 12. End Function 13. Function ObterTodos() As DataSet Implements BS.ITemplate.ObterTodos 14. Dim dsretorno As DataSet 15. Dim SGBD As Unitech.Data.IDatabase = CreateDataBaseInstance(SiglaDataSource) 16. dsretorno = SGBD.GetData("Select * from Template") 17. Return dsretorno 18. End Function 19. End Class Pág.:8

9 No trecho acima, pode-se ver a utilização das principais funcionalidades do UniComponent, que serão descritas em detalhes a seguir Acesso a Banco de Dados O UniComponent fornece aos componentes de negócio/dados das aplicações a possibilidade de acessar base de dados de forma transparente. Essa transparência se dá em dois aspectos: o componente não precisa se acoplar a uma implementação específica do ADO.NET e a string de conexão com o banco de dados não precisa ser mantida/gerenciada em código. Para não acoplar o código do componente à uma bibilioteca de acesso a dados específica do ADO.NET(ex.: SQLServer, Oracle, OLEDB etc), o UniComponent se integra à estrutura IDataBase. Essa estrutura será descrita em detalhes mais adiante, mas representa uma interface genérica de acesso aos dados que pode ser utilizada para qualquer tipo de banco de dados. Para se obter uma instância de uma classe de acesso a dados(idatabase) o método CreateDataBaseInstance deve ser utilizado. Segue um exemplo: Dim SGBD As Unitech.Data.IDatabase = CreateDataBaseInstance( minhaorigemdados ) Resta um questionamento: como definir qual o tipo e qual a string de conexão que será utilizado pelo componente? O UniComponent se utiliza do conceito de OrigemDados(ou DataSource) do UniFW.Net. Uma origem de dados é uma estrutura que permite ao UniFW identificar o tipo de banco de dados assim como sua string de conexão através de uma simples sigla. No exemplo acima, vê-se o uso do método CreateDataBaseInstance, que recebe um parâmetro denominado minhaorigemdados. Para o UniFW, este parâmetro é suficiente para identificar o tipo de banco, assim como a sua string de conexão. Essas informações são obtidas do cadastro de OrigemDados realizado através da interface de acesso a dados do UniFW(ver Guia do Administrador). Outra opção de uso do método CreateDataBaseInstance é sua chamada sem passagem de nenhum parâmetro. Segue exemplo: Dim SGBD As Unitech.Data.IDatabase = CreateDataBaseInstance() Ao não passar nenhum parâmetro para o método CreateDataBaseInstance, será utilizado como OrigemDados(ou DataSource) um valor padrão definido na propriedade SiglaDataSource existente no UniComponent. Esta forma de uso é muito prática quando um determinado componente acessa semrpe a mesma OrigemDados, pois reduz a quantidade de código na chamada de CreateDataBaseInstance, porém, necessita que a propriedade seja atualizada. Um exemplo de atualização da OrigemDados padrão do componente está apresentada abaixo. Public Sub New() SiglaDataSource = "minhaorigemdados" End Sub No trecho acima, vê-se a utilização do construtor do componente de negócio para atualizar a OrigemDados(ou DataSource) que o mesmo irá utilizar por padrão. Pág.:9

10 Geração de Números Seqüenciais Muitas vezes, entidades necessitam de números seqüenciais únicos para serem utilizados como suas chaves primárias, por exemplo. O UniComponent fornece aos componentes de negócio/dados a funcionalidade de geração de números sequenciais. Essa funcionalidade se baseia no recurso de seqüências existente no UniFW.Net e que é configurado através de sua interface de adminsitração(ver Guia do Administrador). O método GetNewNumber do UniComponent recebe como parâmetro a sigla da seqüência desejada. Segue um exemplo de seu uso: Dim X as Integer = GetNewNumber( minhasequencia ) No exemplo acima, é solicitado, através do método GetNewNumber, o próximo número da seqüência de sigla minhasequencia. Para que funcione de acordo, a sequência deve estar devidamente cadastrada na base de dados do UniFW (ver Guia do Administrador) Tratamento de Erros Muito freqüentemente, a rotina de tratamento de erros de componentes possui a mesma lógica. No caso de aplicações que se utilizam do UniFW, o mais comum é identificar se o erro(ou Exception) ocorrido se trata de um erro de négocio ou de ambiente, por exemplo. Outro passo comum é encapsular uma Exception nativa do ambiente em uma outra exception da família Unitech.Exception. O UniFW.Net já fornece um conjunto básico de Exceptions para utilização por parte do desenvolvedor e que serão descritas mais em detalhes adiante. São duas as classes de Exceptions mais utilizadas : Unitech.Exception.EnvironmentException e Unitech.Exception.ApplicationException. EnvironmentExceptions são erros de ambiente, muitos deles imprevisíveis para o desenvolvedor. Pode-se citar como exemplo a impossibilidade de abrir conexão com o banco de dados. Já ApplicationExceptions são erros de aplicação/negócio. Ou seja, são erros que já são esperados pelo desenvolvedor pois os mesmos estão previstos nas validações das regras de negócio da aplicação. Com o objetivo de reutilizar a rotina de tratamento o UniComponent fornece o método TrataErro, declarado da seguinte forma: protected virtual void TrataErro(System.Exception PobjException, string PsigErroAmbientePadrao) O objetivo deste método é identificar o tipo do erro recebido como parâmetro e levantar um erro da família das Unitech.Exceptions. O Unicomponent fornece uma implementação pronta para este método cuja lógica segue abaixo: protected virtual void TrataErro(System.Exception PobjException, string PsigErroAmbientePadrao) { if (this.isbi(pobjexception)) { // Somente lança a exception throw PobjException; } else { // Lança uma nova exception de ambiente, empilhando a anterior throw new Unitech.Exception.EnvironmentException(PsigErroAmbientePadrao, PobjException); } } Pág.:10

11 O método isbi usado acima tem como papel retornar verdadeiro caso a exception recebida como parâmetro possa ser considerada uma exception de negócio(bi=business inteligence). Para responder isso, o mesmo se utiliza de uma propriedade do tipo Hash denominada ChstBIExceptions. Caso a exception recebida como parâmetro esteja nessa Hash, o método retornará TRUE. Segue a implementação básica do método public virtual bool isbi(system.exception PobjException) { return this.biexceptions.containskey(pobjexception.gettype().tostring()); } A Hash com as exceptions que serão consideradas exceptions de negócio(bi) é preenchida através do método CarregaBIExceptions(). Esse método tanto cria a instância da Hash quanto a popula com as exceptions já conhecidas. Segue a lógica interna do método já implementada pelo UniComponent: protected virtual void CarregaBIExceptions() { this.chstbiexceptions = new Hashtable(); this.chstbiexceptions.add("unitech.exception.validacaoexception", null); this.chstbiexceptions.add("unitech.exception.valorinvalidoexception", null); this.chstbiexceptions.add("unitech.exception.valornaodefinidoexception", null); this.chstbiexceptions.add("unitech.exception.tamanhoexception", null); this.chstbiexceptions.add("unitech.exception.applicationexception", null); this.chstbiexceptions.add("unitech.exception.securityexception", null); this.chstbiexceptions.add("unitech.exception.dominioinvalidoexception", null); this.chstbiexceptions.add("unitech.exception.logininvalidoexception", null); this.chstbiexceptions.add("unitech.exception.acessonegadoexception", null); this.chstbiexceptions.add("unitech.exception.usuarionaoautenticadoexception", null); this.chstbiexceptions.add("unitech.exception.intervaloexception", null); } Qualquer código de componentes de negócio/dados podem se utilizar do método TrataErro para tratar seus erros de forma genérica. Como exemplo de seu uso, pode-se tratar um erro ocorrido de acordo com o trecho abaixo: Try... Catch ex as System.Exception End Try TrataErro(ex) Componentes de negócio/dados que estendam do UniComponent, ficam livres para modificar o comportamento padrão de tratamento de erros, bastando para isso a redefinição de um de seus métodos básicos: TrataErro, isbi e CarregarBIExceptions. Pág.:11

12 2.2. Interface IDataBase O ADO.Net disponibiliza diversas bibliotecas de acesso a dados como OLEDB, ORACLE e SQL. Com o tuito de prover um serviço de auditoria de acesso a dados e reduzir o acoplamento do código com a bibliboteca SQLData e ORACLEData, por exemplo, foi criada a interface Unitech.Data.IDatabase. Atualmente, o UniFW disponibiliza as seguintes classes de acesso a dados que implementam a interface IDataBase: SQLDataBase, SQLDataBaseTM, OracleDataBase e OracleDataBaseTM. A figura abaixo apresenta a estrutura do IDataBase: Abaixo será apresentada uma visão geral dos métodos mostrados na figura acima: Execute: Executa a query SQL ou o command passado como parâmetro. Este método deve ser usado, por exemplo, quando deseja fazer insert, delete ou update. FillParameters: Preenche os parâmetros da Procedure com os valores passado no DataRow. Vale lembrar que para fazer a sincronia entre os campos do datarow e os parâmetros da procedure só é feita caso o nome do campo seja igual ao nome do parâmetro. 1. SGBD.SPExecute("SEGURTemplateINS", SGBD.FillParameters("SEGURTemplateINS", tabela.rows(0))) GetData: Obtém dados a partir da query SQL ou command passado como parâmetro. Init: Esse método é responsável por informar a string de conexão ao objeto do tipo IDataBase. Caso a classe herde de UniComponent não será necessário utilizar esse método, pois o método CreateDataBaseInstance de UniComponent já se preocupa em informar a string de conexão ao objeto do tipo IDataBase criado. SPExecute: Executa a procedure passada como parâmetro. Este método deve ser usado, por exemplo, quando deseja fazer insert, delete ou update. SPGetData: Obtém dados a partir da procedure passada como parâmetro. SPGetParameters: Retorna a coleção de parâmetros da procedure passada como parâmetro. 1. Dim Parametros() As System.Data.SqlClient.SqlParameter 2. Parametros = SGBD.SPGetParameters("SEGURUsuarioSELDOM") 3. Parametros(0).Value = IdenDominio 2.3. ResultSets através de Stored Procedures no OracleDatabase e OracleDatabaseTM Diferente do SQLServer o Oracle não retorna um resultset na execução de uma query de consulta, e sim uma referência para um cursor (OracleType.Cursor) o qual é tratada de forma especial dentro da classe OracleDatabase (classe que implementa IDatabase) para retornar finalmente um dataset com o resultset da consulta. Para maiores detalhes sobre a implementação de stored procedures de consulta no Oracle e o seu Pág.:12

13 acesso através do provider OracleClient US;Q322160&ID=KB;EN-US;Q leia o artigo em Diante dessa particulariedade do Oracle em retornar o cursor do resultset ao invés do mesmo, o UniFW.NET obriga que a stored procedure tenha como primeiro parâmetro um CURSOR de direção OUT para a recuperação desse resultset referenciado. Veja o codigo da stored procedure a seguir: PACKAGE PackageUniFW AS TYPE t_cursor IS REF CURSOR ; Procedure SP_APLICACAO(cursor_retorno IN OUT t_cursor, IDENT IN NUMBER); END PackageUniFW; PACKAGE BODY PackageUniFW AS Procedure SP_APLICACAO (cursor_retorno IN OUT t_cursor, IDENT IN NUMBER) IS v_cursor t_cursor; BEGIN OPEN v_cursor FOR SELECT * FROM APLICACAO A WHERE A.IDENTIFICADOR=IDENT; cursor_retorno := v_cursor; END SP_APLICACAO; END PackageUniFW; Acima temos o codigo da criação de um package (linhas 1 a 4) definindo um tipo referente a CURSOR denominada t_cursor e a definição de uma stored procedure chamada sp_aplicacao com a sua respectiva assinatura. Logo a seguir temos o codigo (linhas 6 e 7) da stored procedure SP_APLICACAO que possui como parâmetros cursor_retorno do tipo t_cursor de direção OUT e o IDENT do tipo number. Nas linhas 12 a 16 temos a abertura do meu cursor v_cursor (alias para t_cursor) a qual irá apontar para o resultado da consulta na tabela APLICACAO, através da query SELECT * FROM APLICACAO WHERE A.IDENTIFICADOR=IDENT (linhas 13 a 14). Apesar do que foi relatado acima não existem mudanças quanto a forma de obter dados através de stored procedures em relação ao outros SGBDs. Conforme já foi visto no tópico anterior temos o método SPGetData das classes que implementam IDatabase o qual é responsável pela obtenção de um resultset através de uma stored procedure. Esse método recebe como parâmetros o nome da stored procedure, o nome da tabela que será retornada com o resultset (existe uma assinatura recebendo um array de nomes de tabela não suportado pela OracleDataBase e OracleDataBaseTM) e um array de parâmetros (do tipo IParameters), existem diferentes sobrecargas desse método (inclusive recebendo Command) tornando opcional a informação do nome da tabela assim como a dos parâmetros Abaixo segue um exemplo de código utilizando a funcionalidade: Dim param(0) As OracleClient.OracleParameter param(0) = New OracleClient.OracleParameter("IDENT", 32) Dim ds As DataSet = objdadosoracle.spgetdata("packageunifw.sp_aplicacao", param) No exemplo acima nas linhas 1 e 2 é criado um parâmetro denominado IDENT com o valor 32. Na linha 3 é chamado o método SPGetData da classe OracleDatabase passando o nome da stored procedure (se a stored procedure tiver dentro de um package não se esqueça de informar o nome no seguinte formato: nome_package.nome_storedprocedure) e o parâmetro definido na linha anterior. Note que não se deve informar o 1º parâmetro do tipo Cursor pois essa operação é transparente no processamento do método SPGetData Acesso a dados com UniCommand Os comandos de acesso a dados do ADO.Net são específicos para cada SGBD, ex: SQLCommand, OracleCommand, OleDbCommand, cada um com uma syntaxe específica para montagens de queries parametrizadas. Visando a criação de comandos no padrão ANSI que sirvam para mais de um tipo de SGBD Pág.:13

14 o UniFW disponibiliza a classe UniCommand que possui a inteligência interna de decidir a partir da Sigla da Origem de Dados qual tipo de IDBCommand irá montar para o acesso ao banco. O UniCommand pode gerar SQLCommands, OracleCommands e OleDbCommands. A syntaxe de acesso a dados com um UniCommand fica assim: 1. Dim SGBD as Unitech.Data.IDatabase = CreateDataBaseInstance(getSiglaDataSource) 2. UniCommand cmdsql = new UniCommand(getSiglaDataSource) 3. cmdsql.commandtext = "Select * from Servico where Identificador 4. cmdsql.parameters.add("@id",ds.tables(0).rows(0)("identificador")) 5. dsretorno = SGBD.GetData(cmdSql.ObjCommand,"Servico") O código acima serve para conexões SQL, Oracle ou OleDb. O UniCommand saberá montar internamente o IDBCommand do tipo correto a partir da sigla da origem de dados que lhe foi fornecida. Podese notar que a função GetData (linha 5) recebe como parâmetro a propriedade ObjCommand do UniCommand que possui o command interno gerado corretamente. O mesmo vale para as funções Execute, SPGetData e SPExecute. As chaves dos parâmetros devem estar sempre de acordo com a syntaxe padrão a 2.5. UniComponentBSDB O UniFW.NET com objetivo de facilitar a implementação de classes básicas 1 de negócio/dados disponibiliza o componente UniComponentBSDB 2 que oferece os seguintes recursos e características: 1. Facilidade de implementação através da simplificação. O componente necessita para seu funcionamento tão somente da propriedade SiglaDataSource 3 e informação do nome da tabela padrão (propriedade TabelaPadrao). Em alguns casos específicos da necessidade de utilizar o recurso de Seqüência, será necessário informar a sigla da seqüência (propriedade SiglaSequencia) do cadastro do UniFW.NET assim como o campo seqüencial da tabela (propriedade CampoSequencial). 2. Novas propriedades para manipulação de dados, tais como: o InnerDataSet DataSet com a coleção de tabelas acessadas pelo componente. Inicialmente o componente traz automaticamente a estrutura da tabela padrão 4, essa estrutura por sua vez será uma DataTable com o nome configurado da propriedade TabelaPadrao. o InnerDataTable DataTable referente à tabela padrão. o InnerDataRow DataRow referente a InnerDataTable. É criada uma instância na primeira solicitação dessa DataRow. 1 Entende-se por classes que estão diretamente relacionadas com uma tabela, também denominada de tabelas do sistema, na base de dados. 2 Sendo esse componente uma extensão (herda diretamente) do UniComponent. 3 Propriedade herdade de UniComponent. 4 Nome da tabela padrão foi especificado na propriedade TabelaPadrao. Tabela a qual a classe está diretamente relacionada. Pág.:14

15 3. Obtenção automática da estrutura da tabela padrão, dispensando dessa forma a implementação do método de obtenção do DataStructure 5, antes obrigatório. Obtenção da estrutura de qualquer tabela da origem de dados do componente através do método ObterEstrutura 6. Atenção: A estrutura obtida será adicionada ao InnerDataSet assim como retornada. Um outro aspecto importante que a estrutura obtida da base de dados não incluem as chaves primárias assim como as definições se as colunas das tabela suportam ou não valores do tipo nulo (DBNull). 4. Oferece uma abstração OO do objeto através de propriedades indexadas. Ao instanciar um objeto UniComponentBSDB já é disponibilizado automaticamente uma linha (InnerDataRow) pronta da tabela padrão como propriedade indexada do mesmo. Exemplo: myobjeto( Identificador ) o Essa propriedade indexada acessa indiretamente o InnerDataRow; 5. Automatização de Operações Básicas o ObterPorPK o ObterPorFiltro Estará considerando no filtro somente os campos configurados no InnerDataRow. Atenção: Não é possível configurar um campo no filtro para buscar o valor DBNull. o ObterTodos o Inserir Se tiver configurado a propriedade SiglaSequencia e o campo seqüenciado do InnerDataRow estiver nulo (DBNull) o componente automaticamente realizará o GetNewNumber 7 para esse campo, atualizando o mesmo para futura consulta. o Alterar o Excluir Atenção: Todas as operações são configuradas através de propriedade indexadas ou acesso direto ao InnerDataRow. Todos métodos de consulta (ObterPorPK, ObterPorFiltro, ObterTodos) atualizam o InnerDataSet com o resultado da mesma, além de retorná-lo por referência. Além disso, os métodos de consulta possuem uma sobrecarga para receber os campos de retorno da consulta note que esse recurso irá trazer ao InnerDataSet uma tabela que não condiz com a estrutura na base de dados. 6. Validação automática dos dados submetidos nas Operações Básicas para os seguintes casos: o Verifica se foi indicada a chave primária 8 na realização das operações de ObterPorPK, Inserir, Alterar e Excluir. o Verifica se foram preenchidos os campos obrigatórios na realização das operações de Inserir, Alterar. Atenção: É disponibilizado o método Validar que pode ser facilmente sobrescrito ou estendido. 5 Método responsável pelo retorno de um DataSet com um DataTable contendo a estrutura da tabela padrão da classe. 6 Esse método atualiza o InnerDataSet com a estrutura obtida além de retorná-lo por referencia. Note que essa estrutura estará disponível no InnerDataSet através de uma DataTable com o nome da estrutura solicitada. 7 Método original de UniComponent. 8 Os campos obrigatórios e a chave primária são obtidos através da configuração do esquema da tabela da base de dados. Pág.:15

16 7. Flexibilidade. O componente flexibiliza ao programador a possibilidade de sobrescrever a implementação de qualquer dos seus métodos, assim como de reutilizar a sua implementação. Todos os recursos pré-existentes no UniComponent se mantiveram possibilitando a realização de implementações mais complexas. o Alguns métodos específicos tais como: Reset Reinicializa o componente descartando o InnerDataSet conseqüentemente o InnerDataTable e InnerDataRow. ResetCacheSchemas Limpa o armazenamento temporário (cache) da aplicação referente às estruturas da tabelas. Para utilizar os recursos de automatização de operações básicas em base de dados tais como ObterEstrutura, ObterTodos, ObterPorFiltro, ObterPorPK, Inserir, Alterar e Excluir disponibilizados pelo UniFW.NET na camada de negócio/dados é necessário que cada classe herde direta ou indiretamente da classe Unitech.Component.UniComponentBSDB. É considerado como boa prática, cada projeto de negócio/dados ter sua classe ComponentBSDB. Essa classe a princípio só precisará herdar de Unitech.Component.UniComponent, porém caso o projeto tenha algum requisito especial para as classes que herdem de UniComponentBSDB basta implementar na classe criada tais requisitos e com isso todas as classes que herdem da mesma possuirá tais características. Como por exemplo, no projeto de negócio/dados do BiblioTech, foi criada a classe BiblioTechComponentBSDB que herda de Unitech.Component.UniComponentBSDB e possui o construtor que informa para a classe pai (UniComponent) qual a sigla da origem de dados que foi cadastrada para a aplicação. Mais detalhes sobre o cadastramento de origem de dados ver o Guia do Administrador. Veja abaixo a implementação de uma classe que implementa UniComponentBSDB para servir como classe base para implementação das classes de negócio e dados Public Class BibliotechComponentBSDB Inherits Unitech.Component.UniComponentBSDB Public Sub New() 'Informe para a classe pai (UniComponentBSDB) qual é a origem dados que 'será utilizada. SiglaDataSource = "BIBLIO" 'Se existir um nome padrão para os campos sequenciados aproveite 'para definir também nessa herança. 'Exemplo: ' CampoSequencial = "Identificador" End Sub End Class A implementação de uma classe a partir da BibliotechComponentBSDB se torna bastante trivial. Vejamos abaixo o código de implementação da classe Editora Public Class Editora Inherits BibliotechComponentBSDB Public Sub New() 'A configuração mais importante está na determinação do nome da tabela 'padrão a qual essa classe fará acesso na base de dados. TabelaPadrao = "Editora" Pág.:16

17 'Se existir um nome diferente para o campo seqüenciado dessa classe 'configure a propriedade CampoSequencial exemplo: ' CampoSequencial = "Codigo" 'O componente UniComponentBSDB (BibliotechComponentBSDB herdar dessa classe) necessita para inserir um registro em uma tabela que possui campo seqüenciador 'o nome da sigla dessa sequência no UniFW.NET SiglaSequencia = "Editora" End Class End Sub Utilizando uma classe que herda de UniComponentBSDB Abaixo teremos alguns trechos de código auto-explicativos que guiarão o programador na utilização de uma classe de negócio e dados implementada a partir de UniComponentBSDB (diretamente ou indiretamente). Obtendo Estrutura da Tabela Padrão ' Editora é uma classe que herda de UniComponentBSDB. Dim objeditora As Editora = New Editora 'InnerDataSet do componente possui uma tabela com estrutura da Tabela Padrão InnerDataSet = objeditora.innerdataset Método ObterEstrutura() ' Editora é uma classe que herda de UniComponentBSDB. Dim objeditora As Editora = New Editora 'Posso obter a estrutura de qualquer tabela da Origem de Dados atual InnerDataSet = objeditora.obterestrutura( Livro ) Método ObterTodos() ' Editora é uma classe que herda de UniComponentBSDB. Dim objeditora As Editora = New Editora 'A consulta é retornada e carregada no InnerDataSet do componente. objeditora.obtertodos() Método ObterPorPK() ' Editora é uma classe que herda de UniComponentBSDB Dim objeditora As Editora = New Editora objeditora("identificador") = Marcados(0)(0) 'Marcados possui a chave procurada. 'A consulta é retornada e carregada no InnerDataSet do componente. InnerDataSet = objeditora.obterporpk() Método ObterPorPK( Lista de Campos ) Método ObterPorPK trazendo somente os campos Nome e Endereco na consulta. Esse recurso também está disponível no ObterPorFiltro() ' Editora é uma classe que herda de UniComponentBSDB Dim objeditora As Editora = New Editora objeditora("identificador") = Marcados(0)(0) 'Marcados possui a chave procurada. 'A consulta é retornada e carregada no InnerDataSet do componente. Pág.:17

18 6. 7. objeditora.obterporpk("nome, Endereco") InnerDataSet = objeditora.innerdataset Método ObterPorFiltro() Método ObterPorFiltro trará todas as linhas no banco de dados que atenderem o filtro no campo Endereco e Telefone ' Autor é uma classe que herda de UniComponentBSDB Dim objautor As Autor = New Autor objautor("endereco") = Marcados(0)(0) 'Outra forma de configurar o componente é acessando direto o InnerDataRow. objautor.innerdatarow("telefone") = Marcados(0)(1) 'A consulta é retornada e carregada no InnerDataSet do componente. objautor.obterporfiltro() InnerDataSet = objeditora.innerdataset Método Inserir() ' Editora é uma classe que herda de UniComponentBSDB que utiliza de Seqüência. Dim objeditora As Editora = New Editora objeditora("nome") = "Abril" objeditora("endereco") = "Rua ABCD" objeditora.inserir() 'Obtém o identificador obtido na Inserção Dim NovoIdentificador As Integer = objeditora("identificador") Método Alterar() ' Editora é uma classe que herda de UniComponentBSDB que utiliza de Seqüência. Dim objeditora As Editora = New Editora objeditora("identificador") = 10 objeditora("endereco") = "Rua EFGH" objeditora.alterar() Método Excluir() ' Editora é uma classe que herda de UniComponentBSDB que utiliza de Seqüência. Dim objeditora As Editora = New Editora objeditora("identificador") = 10 objeditora.excluir() Customizando classes que usam de UniComponentBSDB Conforme foi visto no tópico anterior a classe UniComponentBSDB prover diversas funcionalidades para facilitar a implementação de classes de dados e negócios referentes às tabelas de cadastro. No entanto vão existir casos onde o componente precisará de uma customização em seu comportamento, ou até mesmo uma sobreposição de funcionalidade. Veremos a seguir alguns casos que poderão ser comuns: 1. Validação de uma Operação Pág.:18

19 O componente UniComponentBSDB oferece o método Validar() recebendo o parâmetro com o tipo da operação que irá ser executada. Esse método é chamado antes do componente executar uma operação na base de dados, exceto no caso do ObterTodos(). Conforme vimos no tópico anterior o comportamento padrão desse método é o seguinte: o Verifica se foi indicada a chave primária na realização das operações de ObterPorPK, Inserir, Alterar e Excluir. o Verifica se foram preenchidos os campos obrigatórios na realização das operações de Inserir, Alterar. Os casos acima nem sempre corresponderão a necessidade de negócio das implementações do diadia, muitas das vezes se faz necessário realizar validações de contexto de negócio, como por exemplo a verificação de um intervalo de data, ou do tamanho de um parâmetro do tipo string, entre outras diversas validações. Veremos abaixo um exemplo de implementação o qual iremos validar se o campo endereço não possui um tamanho superior a 50 caracteres, caso o campo esteja inválido estaremos levantando uma exceção Private Const cerrcampotamanhoinvalido As String = "ErrCampoTamanhoInvalido" Protected Overrides Sub Validar(ByVal TipoOperacao As Unitech.Component.UniComponentBSDB.enumTipoOperacao) 'Reaproveito a implementação do Validar do UniComponentBSDB MyBase.Validar(TipoOperacao) If (TipoOperacao = Unitech.Component.UniComponentBSDB.enumTipoOperacao.Inserir Or TipoOperacao = Unitech.Component.UniComponentBSDB.enumTipoOperacao.Alterar) Then 'Só permitirá inserção ou alteração na base de dados do campo Endereco 'com uma string menor ou igual a 50 caracteres. If (InnerDataRow("Endereco").ToString().Length > 50) Then Dim mensagem As String = BS.Dicionario.GetString(cErrCampoTamanhoInvalido, New String() {"campo"}, New String() {"endereco"}) 'Recuperação de Mensagem Dinâmica End If End Sub Throw New Unitech.Exception.ValorInvalidoException(mensagem) End If Como podemos ver no código acima a ampliação do comportamento do método Validar é simples, basta para isso sobrescrever o método, como é realizado na linha 3. Note também que é reaproveitado o comportamento original através da chamada do Validar da classe ancestral (linha 7). Na linha 8 é restringida a validação somente para as operações de Inserir e Alterar. Utilizamos também de uma mensagem de erro dinâmica dicionarizada o qual irá trazer uma informação referenciando o campo endereço. Caso a validação verifique a irregularidade do tamanho campo será levantado um erro de valor inválido com a mensagem descrevendo o mesmo (linha 18). 2. Sobrescrevendo uma operação básica Existirão casos particulares em que será necessário sobrescrever o comportamento padrão do componente referente a alguma operação, tais como Inserir, Alterar, Excluir, ObterPorPk, entre outros. Todos os métodos da componente foram implementados possibilitando uma futura sobreposição. Abaixo temos um exemplo de como re-implementar o método Inserir. Pág.:19

20 <TransactionContext(Transaction.Required, Isolation:=Isolation.ReadCommitted)> _ Public Overrides Sub Inserir() Dim Retorno As Int32 Try Dim cmd As Unitech.Data.UniCommand = New Unitech.Data.UniCommand(SiglaDataSource) Dim query As String 'Monta a query query = "INSERT INTO Editora " & _ "(Identificador, Nome, Endereco) " & _ "VALUES " & cmd.commandtext = query 'Atribui valores aos parâmetros que estão na query montada acima InnerDataRow("Identificador") = GetNewNumber("Editora") cmd.parameters.add("@identificador", InnerDataRow("Identificador")) cmd.parameters.add("@nome", InnerDataRow("Nome")) cmd.parameters.add("@endereco", InnerDataRow("Endereco")) 'Chama o método de Validação do UniComponentBSDB Validar(Unitech.Component.UniComponentBSDB.enumTipoOperacao.Inserir) 'Instancia um objeto do tipo IDataBase de acordo com a sigla da origem 'dados informada no contrutor da classe pai Dim SGBD As Unitech.Data.IDatabase = CreateDataBaseInstance() 'Executa o command passado com parâmetro SGBD.Execute(cmd.ObjCommand) 'Informa ao gerenciador de transação que toda os passos 'do método foi executado com sucesso. TransactionManager.SetComplete() Catch ex As System.Exception 'Informa ao gerenciador de transação que houve problemas 'durante a execução do método. TransactionManager.SetAbort() Throw ex End Try End Sub 2.6. Auditoria O UNIFW possui recursos de Auditoria que possibilitam que operações realizadas pelo usuário possam ser auditadas mais adiante. A partir do cadastramento de Trilhas, Alvos e Escopos(ver Guia do Administrador), o UniFW automaticamente cria registros de operação(tabela OperacaoAuditoria) com as seguintes informações: Identificador: chave primária. Número que identifica unicamente um registro de operação criado pelo UniFW. IdenTrilhaAuditoria: identificador da trilha de auditoria que enquadrou a operação realizada em seu escopo e alvo, provocando a sua criação. IdenUsuario: Identificador do Usuário que está solicitando a execução da operação. IdenTela: identificador da Tela utilizada para solicitação da operação. IdenFuncao: identificador da função associada com a operação solicitada. Data: data em que a operação foi solicitada. EnderecoRemoto: Endereço IP, ou Host, da máquina cliente usada para solicitar a operação. SiglaDominioUsuario: sigla do domínio do usuário que está solicitando a execução da operação. LoginUsuario: login do usuário que está solicitando a execução da operação. NomeUsuario: nome do usuário que está solicitando a execução da operação. Interface: definição da interface utilizada para executar a operação. Usado o padrão SiglaAplicacao/SiglaModulo/NomeTela Função: nome da função que está relacionada com a operação solicitada. Ex.: Cadastrar Funcionário Pág.:20