CentroSoftware.SamWebApiSdk 0.12.0

SamWebApiSdk

Libreria .NET di interfacciamento al Web Service 6.0

Obiettivi

La libreria ha lo scopo di fornire un’interfaccia facilitata alla Web API SAM 6.0.

L’organizzazione dei metodi di lettura e scrittura segue l’organizzazione dei moduli SAM secondo la struttura modulo.risorsa.operazione, rendendo facilmente individuabili le risorse disponibili.

I modelli di input e di output sono mappati all’interno della libraria in opportune classi, ereditabili ed estendibili, che rendono immediato l’accesso a ogni campo disponibile sulle sulle risorse di SAM.

La libreria presenta anche alcuni metodi di aggregazione che “dietro le quinte” utilizzano più chiamate alla Web API. Questi metodi creano un ulteriore layer di astrazione rispetto alla struttura base di SAM che snellisce e semplifica ulteriormente l’accesso alle risorse e ne semplifica la manipolazione.

Queste funzionalità consentono un’esperienza di sviluppo guidata che velocizza i tempi di realizzazione di un software integrato con SAM ERP2, riducendo drasticamente la probabilità di errori di sintassi rispetto all’utilizzo diretto tramite chiamate HTTP della Web API.

Prerequisiti

Prima di poter utilizzare la libreria è necessario disporre di un accesso a un ambiente SAM ERP2 in versione 6.0 con installato e attivo il servizio della Web API.

Come iniziare

Scaricare Visual Studio Code o l'editor preferito per lo sviluppo .NET

Scaricare l'ultima versione del framework .NET seguendo le istruzioni qui riportate

Aprire il terminale e verificare la corretta installazione del framework lanciando il seguente comando

dotnet

Se l'installazione è andata a buon fine dovrebbe comparire qualcosa di simile a questo <img src="https://user-images.githubusercontent.com/69239337/157205886-58520cfe-929c-4d9e-9db5-980703a634db.png" width="400px">

Sul terminale, posizionarsi alla cartella nella quale si vuole creare il progetto e crearlo tramite il comando

dotnet new console -o MyApp

Verrà creata la cartella MyApp contenente un nuovo progetto di tipo Console Application

Chiudere il terminale e aprire VS Code e scegliere come cartella di lavoro la cartella MyApp appena creata.

Se non già suggerito da VS Code, installare l'estensione C# tramite questo link o cercandola fra le estensioni di VS Code. Dare il consenso ad eventuali altri avvisi proposti da VS Code.

Aprire il terminale integrato di VS Code tramite Ctrl+J o Command+J

Eseguire il comando

dotnet run

e verificare che venga scritto nella console la string "Hello World!". A questo punto l'ambiente di sviluppo .NET è pronto.

Modificare il file MyApp.csproj con il riferimento alla libreria aggiungendo la sezione ItemGroup e indicando l'ultima versione disponibile della libreria SamWebApiSdk (l'ultima versione è identificabile consultando i packages presenti in questo repository)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="SamWebApiSdk" Version="0.1.0" />
  </ItemGroup>
</Project>

Al salvataggio del file confermare l'avviso di VS Code per il ripristino dei pacchetti oppure eseguire il comando dotnet restore

Se tutto è andato a buon fine è ora possibile istanziare, nel file Program.cs la classe SamWebApi impostando url della Web API, la versione della Web API che si desidera utilizzare, username, password e codice azienda.

Modificare il file Program.cs nel modo seguente

using System;
using System.Threading.Tasks;
using System.Linq;
using CentroSoftware.Api;
using CentroSoftware.Api.Models.Base;

namespace MyApp
{
  class Program
  {
    static async Task Main(string[] args)
    {
        var sam = new SamWebApi("http://url.server.api/api", ApiVersion.v1, "username", "password", "codice_azienda");
        Counterpart counterpart = (await sam.Base.Counterparts.GetAllAsync()).Data.First();
        string ragioneSociale = counterpart.Descr1;

        Console.WriteLine(ragioneSociale);
    }
  }
}

Lanciando il comando

dotnet run

nella console dovrebbe essere scritta la ragione sociale della prima controparte trovata sull'azienda SAM a cui ci si è interfacciati

Esempi

• Utilizzo Querystring

  La query string si utilizza tramite la classe SamWebApiQueryString e i filter factory che sono

  • FilterConditionFactory
  • RqlFilterConditionFactory
  • SortConditionFactory

  L'esempio seguente mostra come estrarre le controparti delle province di Bologna e Milano che sono clienti, ordinate per ragione sociale

  var filtroBolognaMilano = RqlFilterConditionFactory<Counterpart>.Create(x => x.Prov, RqlInclusionFilterConditionType.In, new List<string> { "BO", "MI" });
  var filtroIsCli = RqlFilterConditionFactory<Counterpart>.Create(x => x.Iscli, RqlComparisonFilterConditionType.Equal, true);
  var filtro = RqlFilterConditionFactory.Create(RqlUnionFilterConditionType.And, new List<RqlFilterCondition> { filtroBolognaMilano, filtroIsCli });
  var ordinamento = SortConditionFactory<Counterpart>.Create(x => x.Descr1, SortConditionDirection.Ascending);
  var queryString = new SamWebApiQueryString(1, 20, filtro, ordinamento);
  
  var counterparts = (await sam.Base.Counterparts.GetAllAsync(queryString)).Data;
  

• Utilizzo Querystring manuale

  La query string può anche essere scritta a mano. Per chi ha una buona conoscenza dei campi di SAM, per query string semplici, la definizione manuale può risultare più immediata da scrivere.

  Il seguente esempio riproduce la stessa identica chiamata dell'esempio precedente.

  var manualQueryString = new SamWebApiQueryString("pageNo=1&pageSize=20&sort=+Descr1&rql=and(in(Prov,["BO","MI"]),ne(Iscli,0))");
  
  var counterparts = (await sam.Base.Counterparts.GetAllAsync(manualQueryString)).Data;
  

• Esempio POST

  La creazione di nuove entità sfrutta la classe PropertyChangeTracker e consente di indicare solo alcuni campi lasciando la gestione dei default alla Web API. L'esempio seguente mostra come creare un nuovo cliente con un agente assegnato

  var trackerCounterpart = PropertyChangeTracker<Counterpart>.Create(new Counterpart());
  trackerCounterpart.Set(x => x.Descr1, "New Customer SRL");
  trackerCounterpart.Set(x => x.Prov, "BO");
  trackerCounterpart.Set(x => x.Indiri, "Via Stalingrado");
  int newCounterpartId = await sam.Base.Counterparts.CreateAsync(trackerCounterpart);
  
  var trackerCustomer = PropertyChangeTracker<Customer>.Create(new Customer());
  trackerCustomer.Set(x => x.Idpersona, newCounterpartId);
  trackerCustomer.Set(x => x.Idagente, 19);
  int newCustomerId = await sam.Base.Customers.CreateAsync(trackerCustomer);
  

• Esempio PUT

  La modifica di una entità sfrutta anch'essa la classe PropertyChangeTracker per indicare i soli campi che si desidera modificare. L'esempio seguente mostra come modificare l'indirizzo della controparte create nell'esempio precedente

  var trackerCounterpart = PropertyChangeTracker<Counterpart>.Create(new Counterpart());
  trackerCounterpart.Set(x => x.Indiri, "Via Stalingrado 1234");
  await sam.Base.Counterparts.UpdateAsync(1737, null, trackerCounterpart);
  

• Campi EXT

  Dalla versione di 6.7 della SAM Web API sono gestiti i campi custom sulle tabelle SQL di SAM.

  Per convenzione questi campi devono chiamarsi con il prefisso ext_.

  Ad esempio consideriamo due campi custom aggiunto alla tabella ArtCla1 con il seguente script SQL

  ALTER TABLE ARTCLA1 ADD Ext_FieldOne NVARCHAR(100)
  ALTER TABLE ARTCLA1 ADD Ext_FieldTwo INT
  

  Per gestire questi nuovi campi la libreria SamWebApiSdk mette a disposizione l'attributo DatabaseExtField con il quale si possono marcare i nuovi campi in una classe che eredita dalla classe standard ArticleClassifierOne. Si può quindi definire come segue la classe ArtClaOneCustom

  public class ArtClaOneCustom : ArticleClassifierOne
  {
      [DatabaseExtField]
      public string Ext_FieldOne { get; set; } = null!;
  
      [DatabaseExtField]
      public int? Ext_FieldTwo { get; set; }
  }
  

  Di seguito un esempio di GET di un classificatore articolo sfruttando la classe ArtClaOneCustom

  var artClaOneCustom = await sam.GetOneItemAsync<ArtClaOneCustom>(ResourceNames.ArticleClassifierOne, 1);
  

  E una modifica PUT tramite PropertyChangeTracker

  var artClaOneCustomTracker = PropertyChangeTracker.Create(new ArtClaOneCustom());
  artClaOneCustomTracker.Set(x => x.Ext_FieldOne, "abcdef");
  artClaOneCustomTracker.Set(x => x.Ext_FieldTwo, 123);
  await sam.UpdateItemAsync(ResourceNames.ArticleClassifierOne, 1, null, artClaOneCustomTracker.Entity, artClaOneCustomTracker.ChangedProperties);
  

Compatibilità

La libreria SamWebApiSdk è sviluppata in .NetStandard 2.0 il che la rende compatibile con le applicazioni .NetFramework dalla versione 4.6.1 e le applicazioni .NetCore dalla versione 2.0 (Maggiori informazioni sulla compatibilità)

Sviluppi futuri