6º Dia do ACBr (2024) - Workshop | Configurando os ambientes C#, Java e PHP com as bibliotecas ACBr

[renato.rubinho]

Olá pessoal,

Conforme prometido no workshop, seguem detalhes da apresentação, utilizando a biblioteca ACBrLibNFe da convenção de chamadas Cdecl, compilando em x64.

• Baixando a Lib e identificando a versão que será utilizada
• Configurando o ambiente C#
• Configurando o ambiente PHP
• Configurando o ambiente Java com NetBeans

1. Baixando a Lib e identificando a versão que será utilizada

• Para download das versões completas para os usuários do ACBr PRO, acesse este link.
• Para download das versões DEMO, acesse este link.

1.1. Localize a biblioteca que deseja e acesse seu link para a página de download

1.1.1. Na página seguinte, clique no botão "Download" para baixar o pacote, com a bilioteca e dependências necessárias para sua execução.

1.2. Conteúdo do pacote 

1.2.1. bin

• Pasta onde se encontram as compilações da biblioteca

1.2.2. dep

• Pasta contendo as dependências, sendo Dlls da OpenSSL, LibXml2, schemas, ini de serviços ou outras eventuais que sejam necessárias

1.2.3. log

• Contém o log do componente, que é core da biblioteca, e também o log de alterações na biblioteca

1.3. Versões Single Thread e Multi Thread

1.3.1. As Versões Single Thread ficam localizadas na pasta raiz da bin

1.3.2. As Versões Multi Thread ficam localizadas na pasta MT

1.4. Convenção de chamada: Cdecl ou StdCall ?

* Acesse este link, da documentação da Lib, para maiores detalhes.

2. Configurando o ambiente C#

2.1. Caminho dos programas de exemplo

• Programas de exemplo em:  ..\trunk2\ACBr\Projetos\ACBrLib\Demos\C#   
• Pasta Shared - Core compartilhado: ..\trunk2\ACBr\Projetos\ACBrLib\Demos\C#\Shared

2.2. Soluções Single Thread (sem sufixo) ou Multi Thread (com sufixo MT)

• As soluções Multi Thread possuem o sufixo MT e as Single Thread não possuem sufixo.
• Dentro da pasta do programa de exemplo, acesse a pasta Demo e selecione a solução que irá utilizar.

2.3. Plataformas da solução: x86 ou x64

• Acesse o Gerenciador de Configurações
• Selecione Novo, em Plataforma da solução ativa, e preencha x86 ou x64, de acordo com a arquitetura que deseja compilar

2.4. Salvando a biblioteca e as dependências

• Acesse a pasta bin, x86 ou x64 (de acordo com o que configurou no item 2.3), Debug e crie uma nova pasta ACBrLib
• Dentro da pasta ACBrLib, crie uma nova pasta x86 ou x64, de acordo com o que configurou no item 2.3

2.4.1. Neste novo caminho que foi criado, salve a biblioteca que irá utilizar e suas dependências

2.4.2. Atenção para pegar a bibliteca correta da pasta bin, extraída do pacote baixadose for Single Thread, conforme citado no item 1.3

• Para versão Single Thread, copie a biblioteca das pastas na raiz da bin: ..\pasta extraída do pacote\bin

• Para versão Multi Thread, copie a biblioteca das pastas que se encontram dentro de MT: ..\pasta extraída do pacote\bin\MT

2.4.3. Faça o mesmo para as dependências, sempre tomando o cuidado de pegar as dlls da arquitetura em que compila a aplicação, conforme o item 2.3

2.5. Compile e execute o programa de exemplo

2.6. Siga os passos indicados no item 5 para as configurações básicas para execução do programa de exemplo, elas serão as mesmas para todas as linguagens e o programa de exemplo estará pronto para funcionar

2.7. NuGet

• Para todas as bibliotecas do ACBr foram criados pacotes nuget para as classes de alto nível e o core.

2.7.1. Primeiro devemos remover o core e as classes de alto nível da solução

2.7.2. Acessar o Gerenciador de pacotes do nuget, no menu ferramentas

2.7.3. Pesquisar por ACBrLib

• Selecionar o pacote da bibliteca que vamos instalar
• Atenção, pois existem pacotes para Single Thread e Multi Thread, sendo o Single Thread sem sufixo e o Multi Thread com o sufixo MT
• Selecionamos o pacote, à direita a versão e clicamos em instalar
• Como os pacotes tem dependência do core, automaticamente o core também será instalado

 

2.7.4. Na janela seguinte, confirmamos a instalação

2.7.5. Caso existam versões mais recentes dos pacotes, serão exibidas na aba "Atualizações"

• Neste exemplo, a NFe tinha dependêcia a partir de uma versão anterior à atual do core
• Ao instalar o core, ele foi listado como tendo uma atualização
• Recomenda-se manter sempre a última versão para obter todos os recursos disponibilizados
• A opção de atualização será útil também para futuras alterações nas classes de alto nível

2.7.6. Os pacotes instalados serão listados na aba "Instalado"

2.7.7. Ao compilar a solução, já estará funcionando com os nugets.

3. Configurando o ambiente PHP

3.1. Caminho dos programas de exemplo

• Programas de exemplo em:  ..\trunk2\ACBr\Projetos\ACBrLib\Demos\PHP  
• ACBrComum - Funções em comum centralizadas: ..\trunk2\ACBr\Projetos\ACBrLib\Demos\PHP\ACBrComum

3.2. Soluções Single Thread (sem sufixo) ou Multi Thread (com sufixo MT)

• As soluções Multi Thread possuem o sufixo MT e as Single Thread não possuem sufixo.
• Dentro da pasta do programa de exemplo, acesse a pasta Demo e selecione a solução que irá utilizar.

3.3. Passo a passo para configurar um ambiente com Php-8 + Apache

• Caso esteja iniciando no PHP, neste link existe um passo a passo completo ensinando como configurar o ambiente do zero 

3.4. Habilitando o FFI no php.ini

• Para consumo das bibliotecas do ACBr no PHP, vamos utilizar a extensão FFI
• Ela foi disponibilizada no PHP a partir da versão 7.4.0, caso esteja com uma versão anterior a esta, será preciso atualizar o PHP
• Acesse o php.ini, na pasta onde o php foi instalado
• Remova o comentário da extension=ffi
• Procure pela seção ffi, remova o comentário de ffi.enable e preencha como true
• Após salvar o arquivo, reinicie o servidor de internet

3.5. Verificando FFI no phpinfo()

• Quando o FFI estiver habilitado, ele será exibido no phpinfo

3.6. Acesse ..\trunk2\ACBr\Projetos\ACBrLib\Demos\PHP e copie as pastas do programa de exemplo que irá utilizar e da ACBrComum para a raiz do seu servidor de internet

3.7. As pastas dos programas de exemplo já foram enviadas para o SVN com a estrutura de pastas onde devem ser salvas a Lib e as dependências

• Acesse a pasta MT ou ST, de acordo com o programa de exemplo que irá utilizar
• Depois ACBrLib
• E por último a pasta x86 ou x64, dependendoda versão do seu ambiente PHP

3.8. Dentro da pasta da arquitetura que selecionou, haverá um arquivo Leia-me instruindo qual a biblioteca que deverá ser salva naquele local

• Copie a biblioteca e as dependências, conforme instruído nos itens 2.4.2 e 2.4.3
• Lembrando sempre em tomar cuidado com a versão ST ou MT, conversão de chamadas e arquitetura

3.9. Os programas de exemplo possuem uma página única para ST e MT: ACBrNFeBase.php

3.9.1. Para acessar a versão que deseja, selecione o arquivo com o sufixo desejado

• ACBrNFeDemoST.php: Para Single Thread
• ACBrNFeDemoMT.php: Para Multi Thread

3.10. Exemplo acessando a versão Multi Thread

• Como a pasta do programa de exemplo foi salva na raiz do servidor de internet, acessaremos localhost/NFe/ACBrNFeDemoMT.php
• Siga os passos indicados no item 5 para as configurações básicas para execução do programa de exemplo, elas serão as mesmas para todas as linguagens e o programa de exemplo estará pronto para funcionar

3.11. Servidor linux sem ambiente gráfico

• Este item esta sendo analisado e traremos mais informações assim que houver uma resposta

3.11.1. As bibliotecas do ACBr possuem dependência de ambiente gráfico devido ao motor de relatórios utilizado

• Estamos trabalhando para utilizar somente o FPDF e, com isso, acabar com essa dependência
• Enquanto isso não acontece, para servidores que não possuem ambiente gráfico, é necessário que seja instalado um emulador, como o XVFB
• Segue um dos nossos cursos para os usuários PRO onde esse assunto foi abordado

3.11.2. Com o emulador instalado, é necessário incluir a linha a seguir nos fontes antes de carregar a Lib

putenv("DISPLAY=:99");

3.11.3. Isso já foi tratado nas funções da ACBrComum.php

4. Configurando o ambiente Java com NetBeans

4.1. Caminho dos programas de exemplo

• Programas de exemplo em:  ..\trunk2\ACBr\Projetos\ACBrLib\Demos\Java  
• ACBr Common - Core compartilhado: ..\trunk2\ACBr\Projetos\ACBrLib\Demos\Java\ACBr Common

4.2. Projetos Single Thread (sem sufixo) ou Multi Thread (com sufixo MT)

• As soluções Multi Thread possuem o sufixo MT e as Single Thread não possuem sufixo.
• Dentro da pasta do programa de exemplo, acesse a pasta Demo e selecione a solução que irá utilizar.

4.3. Abra os projetos ACBr Common e o da pasta Imports que contém os binds dos métodos da bblioteca

4.4. Plataformas dos projetos: x86 ou x64

• Siga os passos nos 3 projetos
• Botão direito sobre o projeto, Propriedades
• Acesse Libraries
• Em Java Plataform, selecione a JDK da arquitetura que irá compilar e confirme

4.5. Acesse a pasta do programa de exemplo que carregou

• Crie a pasta ACBrLib 
• Dentro de ACBrLib, crie a pasta x86 ou x64 de acordo com a arquitetura que irá compilar

• Diferente das outras linguagens mostradas anteriormente, o java não vai considerar as depedências dessa pasta, então vamos salvar somente a biblioteca

4.5.1. Para o projeto enxergar a biblioteca, vamos configurar o caminho criado para salvar a dll

• Acesse as propriedades do projeto do programa de exemplo
• Em Libraries, do lado direito, na aba Compile, clique no botão com sinal de [ + ], ao lado de Classpath
• Clique na opção Add JAR/Folder
• Selecione a pasta x86 ou x64 que foi criada no item anterior

4.6. Compile e execute o programa de exemplo

• Siga os passos indicados no item 5 para as configurações básicas para execução do programa de exemplo, elas serão as mesmas para todas as linguagens e o programa de exemplo estará pronto para funcionar

5. Configurações básicas para utilização do programa de exemplo

5.1. Na aba Geral, configure a "Pasta dos Logs" e a "Pasta dos Schemas"

* No pacote onde a lib foi baixada, a pasta de schemas da NFe estará disponível em \dep\Schemas\NFe

5.2. Na aba Arquivos, configure: "Pasta Arquivos NFe", "Pasta Arquivos Inutilização" e "Pasta Arquivos Evento"

5.3. Na aba Webservices

• SSL Type: No momento da criação deste tópico, o padrão utilizado por todos os DFes é TLS1.2, selecione a opção LT_TLSv1_2
• TimeOut: Configure o padrão 30k, lembrando que este é o limite de tempo de execução da sua chamada, o que quer dizer que será o tempo máximo que a aplicação irá esperar de resposta, caso o serviço responda em menos tempo, o retorno será neste tempo.
• Salvar envelope SOAP: Contém os envelopes soap enviados para para o serviço consumido e podem ser úteis para análise em casos de eventuais problemas.

5.4. Na aba Certificados

5.4.1. Configurando certificado A1

• Recomendamos sempre a utilização da OpenSSL para certificados A1, pois ela é autossuficiente e não depende de atualizações do Sistema Operacional.
• Configure a CryptLib e HttpLib como OpenSSL e a XmlSignLib como LibXml2
• Para utilização do certificado salvo em disco, preencha o caminho do certificado no campo "Caminho" ou para pegar o conteúdo do certificado em um banco de dados, por exemplo, preencha "Dados PFX"
• Para ambos, preencha a senha do certificado

 

5.4.2. Configurando certificado A3

• Lembrando sempre que o certificado A3 é historicamente muito problemático, pois aprensenta problemas com driver, falhas devido a atualizações do Windows e outros.
• Requer que todas as atualizações do windows estejam em dia
• Configure a CryptLib como cryWinCrypt, HttpLib como httpWinHttp e a XmlSignLib como xsLibXml2
• Configure a senha e o Número de Série do certificado

5.5. Com essas configurações o programa de exemplo estará pronto para funcionar