Tutorial C#: come utilizzare le API di Perfetto con B.O.E.N.

Sommario
Nel presente articolo sono descritti i passi da seguire per poter creare un esempio di un web service scritto in linguaggio C# e fruibile dalla tecnologia B.O.E.N.

Il web service dell'esempio espone due metodi che saranno richiamati da Perfetto all'inserimento del documento, Rapportino per Commessa. Il primo metodo sarà invocato prima del salvataggio del documento ed effettuerà un controllo di validità dei dati. Il secondo metodo sarà chiamato dopo il salvataggio del documento e inserirà il Rapportino per Commessa in un'altro database aziendale.

Per facilitare la lettura dell'articolo di seguito un indice dei paragrafi dell'articolo:

• Creazione del progetto
• Creazione del Web Service
• Creazione dei metodi web
• Pubblicazione del web service
• Creazione del file di sottoscrizione

Creazione del progetto

• Aprire "Visual Studio", in questo esempio è stato utilizzato Visual Studio 2010
• Selezionare "Nuovo progetto..."
• Scegliere "Applicazione Web ASP.NET"
• Inserire il nome del progetto "WebServiceSample"
• Premere il pulsante "Ok"

Creazione del Web Service

• Aprire "Espora soluzioni" del progetto
• Fare click destro sul progetto, apertura menu
• Selezionare la voce "Aggiungi", apertura sotto menu
• Scegliere "Nuovo elemento..."
• Selezionare "Servizio Web"
• Inserire il nome del Servizio Web "WorkingReportManager"
• Premere il pulsante "Aggiungi"

 Creazione dei metodi web
In questo paragrafo sono descritti i metodi web che devono essere invocati da Perfetto in fase di inserimento del documento Rapportino di Commessa. 

• Creare i metodi web con firma deve rispettare le specifiche descritte nell'articolo La funzione B.O.E.N. (Business Object Events Notification):

  [WebMethod]
  public bool BeforeInsertWorkingReport(string callerNS, 
                                       int action, 
                                       string when, 
                                       string[] dataExport, 
                                       ref string[] returnMessages)
  {
  
  }
  public bool AfterInsertWorkingReport(string callerNS, 
                                       int action, 
                                       string when, 
                                       string[] dataExport, 
                                       ref string[] returnMessages)
  {
  
  }

• Istanziare un oggetto ArrayList che dovrà contenere i messaggi del metodo web
• Creare la classe CreateReturnMessages che valorizza, il parametro di ritorno retunMessage del metodo web, con i messaggi contenuti nell'ArrayList msgList

  private ArrayList msgList = new ArrayList();
  
  private void CreateReturnMessages(ref string[] returnMessages)
  {
     returnMessages = new string[msgList.Count];
  
     for (int idx = 0; idx < msgList.Count; idx++)
     {
        returnMessages[idx] = msgList[idx].ToString();
     }
  }

• Creare la classe CreateXPath che aggiunge al nome di un nodo il prefisso corretto

  private string CreateXPath(string prefix, string xPathString)
  {
     string res = string.Empty;
     foreach (string s in xPathString.Split('/'))
     {
        if (res != string.Empty)
          res += "/";
        res += (prefix + ":" + s);
      }
  
      return res;
  }

• Inserire, all'interno del metodo web BeforeInsertWorkingReport, le operazioni di lettura del documento, di controllo dei valori inviati e di gestione dei messaggi da ritornare a Perfetto
  

  [WebMethod]
  public bool BeforeInsertWorkingReport(string callerNS, int action, string when, 
                                  string[] dataExport, ref string[] returnMessages)
  {
     bool bOk = true;
     try
     {
       XmlDocument xDoc = new XmlDocument();
       xDoc.LoadXml(dataExport[0]);
  
       XmlNamespaceManager nsmSchema = new XmlNamespaceManager(xDoc.NameTable);
       nsmSchema.AddNamespace(xDoc.DocumentElement.Prefix, 
                              xDoc.DocumentElement.NamespaceURI);
  
       foreach (XmlNode n in xDoc.SelectNodes(CreateXPath(xDoc.DocumentElement.Prefix, 
                                                "Rapportino/Data/RapportinoCommessa"), 
                                                 nsmSchema))
       {
         XmlNode nJob= n.SelectSingleNode(CreateXPath(xDoc.DocumentElement.Prefix, 
                                                      "Job"), nsmSchema);
         XmlNode nExtRef = n.SelectSingleNode( CreateXPath(xDoc.DocumentElement.Prefix, 
                                                       ExternalReference"), nsmSchema);
  
         if (nJob == null || nExtRef == null)
         {
            msgList.Add("Wrong export data");
            bOk = false;
            continue;
         }
  
         string sJob = nJob.InnerText;
         string sExtRef = nExtRef.InnerText;
  
         if (sExtRef == string.Empty)
         {
           msgList.Add(string.Format("ExternalReference is empty! 
                                  Cannot insert the working report for Job {0}", sJob));
           bOk = false;
           break;
         }
      }
    }
    catch (Exception tbExc)
    {
      msgList.Add(string.Format("Exception occurred: {0}!", tbExc.Message));
      bOk = false;
    }
    CreateReturnMessages(ref returnMessages);
    return bOk;
  }

• Creare un metodo che dato un Rapportino per Commessa in formato xml, inserisca il documento in un'altro database aziendale

   private bool InsertWRInCompany(string xmlDoc)
   {
     bool bOk = true;
     string authToken = string.Empty;
     string user = "your user";
     string company = "company name";
     string password = "your password";
     string prodKey = "your code";
   try
   {
     int nResult = aLoginManager.LoginCompact(ref user, ref company, 
                                              password, prodKey, false, out authToken);
   string strResult = string.Empty;
   if (nResult == 0)
   {
     authenticationToken = authToken;
     string elToken;
     int res = aTbServices.CreateTB(authenticationToken, applicationDate, 
                                    true, out elToken);
     if(res > 0)
     {
       if (aTbServices.SetData(authenticationToken, xmlDoc, applicationDate, 1, false, 
                               out strResult))
       {
          msgList.Add(string.Format("Insert Working Report in {0}", company));
       }
       else
       {
         bOk = false;
         XmlDocument doc = new XmlDocument();
         doc.LoadXml(strResult);
         XmlNamespaceManager xmlNsManager = new XmlNamespaceManager(doc.NameTable);
         xmlNsManager.AddNamespace(doc.DocumentElement.Prefix, 
                                   doc.DocumentElement.NamespaceURI);
         string strMessage = string.Empty;
         foreach (XmlNode node in doc.SelectNodes(CreateXPath(doc.DocumentElement.Prefix, 
                                    "Rapportino/Diagnostic/Errors/Error"), xmlNsManager))
         {
           strMessage += node.SelectSingleNode(CreateXPath(doc.DocumentElement.Prefix, 
                                               "Message"), xmlNsManager).InnerText;
         }
         msgList.Add(string.Format("Inserting failded! Some error occurred!\n {0}", 
                                   strMessage));
        }
      }
      else
      {
        msgList.Add(string.Format("Inserting failded! Error number: {0}", res));
        bOk = false;
      } 
      aTbServices.CloseTB(authenticationToken);
    }
    else
    {
      bOk = false;
      msgList.Add(string.Format("Inserting failded! Error occurred, code: {0}", 
                                 strResult));
    } 
   }
   catch (Exception logExc)
   {
     msgList.Add(string.Format("Inserting failded! Exception occurred: {0}", 
                                logExc.Message));
   }
   return bOk;
  }

• Inserire, all'interno del metodo web AfterInsertWorkingReport, il metodo, InsertWRInCompany, che inserisce il Rapportino per Commessa in un'azienda

   [WebMethod]
   public bool AfterInsertWorkingReport(string callerNS, int action, string when,
                                        string[] dataExport, ref string[] returnMessages)
   {
     bool bOk = true;
     try
     {
       XmlDocument xDoc = new XmlDocument();
       xDoc.LoadXml(dataExport[0]);
  
       XmlNamespaceManager nsmSchema = new XmlNamespaceManager(xDoc.NameTable);
       nsmSchema.AddNamespace(xDoc.DocumentElement.Prefix, xDoc.DocumentElement.NamespaceURI);
  
       foreach (XmlNode n in xDoc.SelectNodes(CreateXPath(xDoc.DocumentElement.Prefix, 
                              "Rapportino/Data/RapportinoCommessa"), nsmSchema))
       {
         XmlNode nNumber = n.SelectSingleNode(CreateXPath(xDoc.DocumentElement.Prefix, 
                                                "WorkingReportNo"), nsmSchema);
         XmlNode nDate = n.SelectSingleNode(CreateXPath(xDoc.DocumentElement.Prefix, 
                                                "WorkingReportDate"), nsmSchema);
  
        if (nNumber == null || nDate == null)
        {
         msgList.Add("Wrong export data");
         bOk = false;
         continue;
        }
        string sNumber = nNumber.InnerText;
        string sDate = nDate.InnerText;
        if (sNumber == string.Empty)
        {
         msgList.Add("WorkingReportNo is empty!");
         bOk = false;
         break;
        }
        else
        {
          if (InsertWRInCompany(dataExport[0])) 
           msgList.Add("Successfully inserted!!!"); else msgList.Add("Inserting failded!");
        }
     }
   }
   catch (XmlException XmlExc)
   {
     msgList.Add(string.Format("Exception occurred: {0}!", XmlExc.Message));
     bOk = false;
   }
   aLoginManager.LogOff(authenticationToken);
   CreateReturnMessages(ref returnMessages);
   return bOk;
  }

Pubblicazione del web service
In questa sezione è mostrato come pubblicare il web service dal Visual Studio.

• Fare click destro sul progetto "WebServiceSample", apertura menu
• Scegliere "Proprietà", apertura maschera delle proprietà
• Selezionare dal menu a sinistra la sezione "Web"
• Scegliere "Usa server Web IIS locale"
• Inserire l'URL del progetto "http://localhost/WebServiceSample"
• Premere il pulsante "Crea directory virtuale"

In Gestione Computer è possibile vedere che la directory virtuale è stata creata.

 Creazione del file di sottoscrizione
In questo paragrafo è descritto come creare il file di sottoscrizione in modo tale che Perfetto, al salvataggio di un nuovo Rapportino per Commessa, riesca a invocare i metodi web BeforeInsertWorkingReport e AfterInsertWorkingReport del web service WorkingReportManager. 

• Creare un file con estensione xml e il nome scelto per l'esempio è WR_Subscriptions.
• Valorizzare il file di sottoscrizione con il seguente contenuto:

   <Subscriptions> 
        <Subscription namespace="Document.ImpiantiNet.Rapportini.INRapportini.Rapportino"
                      operation="WM" 
                      profile="Default"
                      action="1" 
                      when="BEFORE"
                      webServer="http://localhost/" 
                      webService="WebServiceSample/WorkingReportManager.asmx"
                      webNS="http://tempuri.org/" 
                      method="BeforeInsertWorkingReport"
                      port="80" 
        /> 
   <Subscription namespace="Document.ImpiantiNet.Rapportini.INRapportini.Rapportino"
                     operation="WM" 
                     profile="Default"
                     action="1" 
                     when="AFTER"
                     webServer="http://localhost/" 
                     webService="WebServiceSample/WorkingReportManager.asmx"
                     webNS="http://tempuri.org/" 
                     method="AfterInsertWorkingReport"
                     port="80" 
   /> 
  </Subscriptions>

  
  Analizzando il contenuto del file è possibile notare che l'attributo "action" uguale a "1" indica che la chiamata ai metodi web scatteranno in fase di inserimento del documento. L'attributo "when"  nella prima sottoscrizione essendo uguale a "BEFORE" specifica che l'invocazione del primo metodo web avverrà prima della transazione, quindi se il valore di ritorno del metodo è false il documento non viene salvato, mentre nella seconda sottoscrizione essendo uguale ad "AFTER" indica che il metodo non inciderà sull'esito della transazione del documento.
• Salvare il file di sottoscrizione in <cartella installazione>/<nome prodotto>/Custom/ Companies/
  <nome azienda>/ActionSubscriptions