Therefore™ Help

Benché siano disponibili molti linguaggi e strumenti, in questa sede viene descritta soltanto la procedura per creare funzioni Azure utilizzando C# in Visual Studio. Questo è l'approccio consigliato perché consente di eseguire il testing e il debugging delle funzioni Azure localmente, senza che sia necessario un abbonamento Azure, semplicemente premendo F5. È anche possibile implementare la funzione in Azure da Visual Studio.

Assicurarsi che Visual Studio sia installato con il carico di lavoro "Sviluppo di Azure".

In Visual Studio, fare clic sul menu "Tools" e poi su "Get Tools and Features…" per aprire il programma di installazione.

Aprire la scheda "Carichi di lavoro" e cercare "Sviluppo di Azure". Attivare la casella di controllo in alto a destra e fare clic su "Modifica" per applicare le modifiche.

Se il carico di lavoro "Sviluppo di Azure" è stato installato correttamente, "Funzioni di Azure" sarà una delle opzioni disponibili quando si crea un nuovo progetto in Visual Studio. Si consiglia comunque di iniziare con l'esempio "EmptyFunctionApp" anziché cominciare una procedura di sviluppo da zero.

Selezionare "Azure Functions v2" ("v1" non sarà più disponibile in futuro) e "Http trigger", poiché Therefore™ attualmente supporta solo la chiamata di funzioni Azure tramite richieste HTTP(S).

I diritti di accesso saranno applicati solo quando la funzione sarà pubblicata, non per lo sviluppo locale. Se si sceglie "Anonymous", non è richiesta alcuna chiave. "Function" invece richiede la chiave funzione, mentre "Admin" richiede la chiave Function App. Si può usare anche la chiave master.

Aggiungere al progetto la cartella "Therefore" dall'esempio “EmptyFunctionApp”.

I file non sono indispensabili, ma rendono lo sviluppo più semplice e più veloce.

Se è necessario aggiornare WebAPIContract.cs a seguito di modifiche apportate all'API web, procedere nel modo seguente:

1.Scaricare e installare Silverlight 5.0 o successivo

2.Verificare che il servizio XML Manager sia in esecuzione

3.Creare una cartella temporanea, ad es. “C:\WebAPI”

4.Aprire una riga di comando e andare a “C:\Program Files (x86)\Microsoft SDKs\Silverlight\v5.0\Tools”

5.Eseguire il comando seguente:

SlSvcUtil.exe http://servername:8000/theservice/v0001?singlewsdl /out: C:\WebAPI \WebAPIContract.cs /config: C:\WebAPI \output /namespace:http://schemas.therefore.net/webservices/interop/v0001/types,Therefore.WebAPI

6.        Andare a “C:\WebAPI“ e copiare il file WebAPIContract.cs nella cartella “Therefore\WebAPI”, sostituendo quello precedente.

Come descritto nel progetto di esempio, la funzione SendRequest della classe Therefore.WebAPI.WebApiClient può essere utilizzata per inviare una richiesta. Per un elenco di tutti i comandi disponibili, consultare la documentazione dell'API web.

Per utilizzare WebAPIContract.cs è necessario il pacchetto NuGet “System.ServiceModel.Http”. Per maggiori informazioni, vedere la sezione Dipendenze.

Aggiungere al progetto la cartella “Therefore” dal campione “EmptyFunctionApp”, quindi eliminare la sottocartella “WebAPI”, che è richiesta solo per le chiamate REST. Poiché l'uso di SOAP non è consigliato, il valore di “UseREST” nella classe TheConfig deve essere impostato su “false”, altrimenti la proprietà WebAPIBaseUrl risulterà errata.

Aggiungere Therefore™ Web API come servizio connesso:

Come servizio connesso, scegliere “Microsoft WCF Web Service Reference Provider”.

Inserire l'URL presso il quale è in esecuzione il servizio web e premere “Go”. Se il servizio è in esecuzione, dovrebbe essere indicato in Servizi come “ThereforeService”.

Specificare uno spazio dei nomi come “Therefore.WebAPI” e premere Fine.

La classe Therefore.WebAPI.ThereforeServiceClient può essere utilizzata per effettuare chiamate API web.

Per maggiori informazioni sul pacchetto NuGet “System.ServiceModel.Http”, vedere la sezione Dipendenze.

Per aggiungere il pacchetto NuGet “System.ServiceModel.Http”, fare clic con il pulsante destro sul progetto e selezionare “Gestisci pacchetti NuGet…”

Passare alla scheda Sfoglia e cercare “System.ServiceModel.Http”, selezionarlo e fare clic su Installa.

Se viene visualizzato l'errore seguente durante la compilazione, è presente un bug non ancora risolto:

System.IO.FileNotFoundException: Could not load file or assembly 'System.Private.ServiceModel, Version=4.5.0.3, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'. Il sistema non è in grado di trovare il file specificato.

Per risolvere questo problema, modificare il file .csproj e aggiungere la seguente configurazione come elemento secondario del nodo radice “Progetto”:

<!--this is temporary workaround for issue https://github.com/dotnet/wcf/issues/2824 also requires nuget package-->

<Target Name="CopySPSM" BeforeTargets="Build">

<Copy SourceFiles="$(USERPROFILE)\.nuget\packages\system.private.servicemodel\
4.5.3\runtimes\win\lib\netstandard2.0\System.Private.ServiceModel.dll" DestinationFolder="$(OutputPath)\bin" />

</Target>

<ItemGroup>

<None Include="$(USERPROFILE)\.nuget\packages\system.private.servicemodel\
4.5.3\runtimes\win\lib\netstandard2.0\System.Private.ServiceModel.dll" CopyToPublishDirectory="Always" />

</ItemGroup>

<!--end workaround-->

Nota: potrebbe essere necessario modificare i numeri di versione e le interruzioni di riga.

EmptyFunctionApp è una breve funzione Azure di esempio che recupera i parametri passati da Therefore™, configura l'oggetto WebApiClient per prepararlo per l'uso e alla fine restituisce i parametri richiesti. È stata creata per essere utilizzata come punto di partenza per ulteriori attività di sviluppo.

public static async Task<IActionResult> Run(

[HttpTrigger(AuthorizationLevel.Function, "post", Route = "v1/Function1")] HttpRequest req, ILogger log)

{

string errMsg = ""; // error message that will be returned to Therefore for logging

Exception logEx = null; // exception details for logging

bool routingDone = false; // false: WF instance will be routed to the next task.

// true: WF instance will not be routed because routing was done by WebAPI call

try…

if (!String.IsNullOrWhiteSpace(errMsg) || logEx != null)

log.LogError(logEx, errMsg); // log the error so it can be viewed in the Azure Portal

TheRespParams respParams = new TheRespParams(errMsg, routingDone);

return new OkObjectResult(respParams.Serialize());

La funzione “Run” è la funzione principale che verrà chiamata in una richiesta HTTP.

Il livello di autorizzazione “AuthorizationLevel” definito in HttpTrigger sarà applicato solo quando la funzione sarà pubblicata, non per lo sviluppo locale. Se si sceglie "Anonymous" non è richiesta alcuna chiave, mentre "Function" richiede la chiave funzione e "Admin" richiede la chiave Function App. Si può usare anche la chiave master.

Il valore “Route” definito in HttpTrigger come “v1/Function1” fornisce un modo per gestire le versioni. Supponiamo che una nuova versione del workflow richieda una nuova versione della funzione, ma che alcune istanze debbano rimanere sulla versione vecchia. Per soddisfare questa esigenza, si potrebbe copiare la funzione e cambiare il valore Route da “v1” a “v2” nel codice e nella configurazione lavoro dei nuovi lavori. Una App per le funzioni può includere più funzioni.

Alla fine del codice campione, gli errori eventualmente verificatisi vengono registrati in Azure e anche passati a un oggetto delle classe “TheRespParams”. La classe “TheRespParams” provvede a convertire i parametri di restituzione obbligatori per Therefore™ come oggetto JSON.

Viene sempre creato un oggetto “OkObjectResult”, che restituisce l'oggetto JSON con codice di stato HTTP 200. Eventuali messaggi di errore in “errMsg” saranno restituiti a Therefore™ per essere registrati nello storico workflow. Sul lato di Therefore™, la chiamata alla funzione ha avuto esito positivo se non si è verificato nessun errore (errMsg è vuoto).

try

{

// read parameters passed by Therefore

string requestBody = await new StreamReader(req.Body).ReadToEndAsync();

TheReqParams reqParams = TheReqParams.Deserialize(requestBody);

if (reqParams == null || reqParams.TheInstanceNo <= 0 || reqParams.TheTokenNo <= 0)

return new BadRequestObjectResult("Mandatory parameter not set"); // function was not called by Therefore, return HTTP error 400

reqParams.LogWFInfo(log); // log workflow information now, in case the function crashes later

// configuration

TheConfig config = TheConfig.Instance;

config.WebAPIBaseUrl = reqParams.TheWebAPIUrl;

config.Tenant = reqParams.TheTenant;

// Web API connection

WebApiClient client;

// specify a user name and password if the permissions from the accessToken would not be sufficient

if (!String.IsNullOrEmpty(config.UserName) && !String.IsNullOrEmpty(config.Password))

// connection with user name and password/token:

client = new WebApiClient(config.UserName, config.Password, config.IsToken, config.WebAPIUrl,

config.Tenant, config.Language, config.RequestTimeout, config.ClientTimezoneIANA);

else

// connection with JWT Bearer token 'accessToken'

client = new WebApiClient(reqParams.TheAccessToken, config.WebAPIUrl, config.Tenant,

config.Language, config.RequestTimeout, config.ClientTimezoneIANA);

// Add your code here

}

“TheReqParams” provvede alla lettura di tutti i parametri passati da Therefore™.

La classe “TheConfig” ha varie proprietà, necessarie per la chiamata WebAPI, come language, timezone, request timeout e molte altre. Possono essere configurate in base alle proprie esigenze oppure lasciate con i valori predefiniti.

Due proprietà non hanno valori predefiniti utili: “WebAPIBaseUrl” e “Tenant”. I valori vengono passati dal server Therefore™ e devono semplicemente essere assegnati all'oggetto “TheConfig”.

La classe TheConfig leggerà le proprietà UserName e Password da “local.settings.json” durante lo sviluppo locale, oppure dalle Impostazioni applicazioni quando si opera in Azure.

Le istanze dell'oggetto WebApiClient possono essere create utilizzando le credenziali utente o il token JWT,

a seconda che le credenziali risultino vuote o meno. Se le credenziali non sono configurate, viene utilizzato il token JWT.

La funzione SendRequest della classe WebApiClient può essere utilizzata per inviare una richiesta. Per un elenco di tutti i comandi disponibili, consultare la documentazione dell'API web.

Nel commento “aggiungere qui il proprio codice”, è possibile eseguire richieste Web API e implementare la propria logica aziendale.

A seconda che l'esito sia negativo o positivo, viene restituito un errore oppure una stringa vuota, per segnalare a Therefore™ se la funzione viene eseguita nel modo previsto (al di fuori dell'istruzione try/catch).

Questa documentazione spiega solo come inviare richieste mediante l'API Web in generale, ma non descrive le singole funzioni disponibili. Per informazioni dettagliate sull'uso delle varie funzioni, consultare la documentazione dell'API web.

Le funzioni API web possono essere chiamate utilizzando la classe Therefore.WebAPI.WebApiClient.

Per creare una nuova istanza sono necessari alcuni parametri. Come descritto nell'esempio EmptyFunctionApp, l'oggetto “TheConfig” può essere di aiuto a questo scopo. Quando si configura un requestTimeout, tenere presente che la funzione stessa viene chiamata tramite una richiesta HTTP e scade dopo un massimo di 230 secondi.

Credenziali:

WebApiClient client = new WebApiClient(username, password, isToken, webApiUrl, tenant, language, requestTimeout, clientTimezoneIANA);

Token bearer JWT:

WebApiClient client = new WebApiClient(bearerToken, webApiUrl, tenant, language, requestTimeout, clientTimezoneIANA);

Dopo aver creato l'oggetto WebApiClient, è possibile inviare le richieste utilizzando la funzione “SendRequest”.

Task<TResp> SendRequest<TReq, TResp>(TReq requestData)

Questa singola funzione può essere utilizzata per tutte le funzionalità dell'API web. La richiesta viene determinata dal tipo di parametro di richiesta e di risposta. Richiesta e riposta devono coincidere. Ad esempio, è possibile utilizzare GetDocumentParams con GetDocumentResponse per eseguire una richiesta “GetDocument”.

Esempio: Recupero di un documento (con file):

È possibile recuperare documenti utilizzando GetDocumentParams con GetDocumentResponse nella funzione SendRequest.

Nel parametro di richiesta GetDocumentParams, è necessario specificare il numero documento.

Se devono essere recuperati anche i file del documento, occorre impostare la proprietà “IsStreamsInfoAndDataNeeded” su true. Se sono necessarie solo le informazioni di flusso (stream) senza i dati veri e propri, “IsStreamsInfoNeeded” può essere impostata su false.

// Create request parameters

GetDocumentParams parameters = new GetDocumentParams();

parameters.DocNo = docNo;

parameters.IsStreamsInfoAndDataNeeded = true;

parameters.IsIndexDataValuesNeeded = true;

// Send the request

GetDocumentResponse docResp = client.SendRequest<GetDocumentParams, GetDocumentResponse>(parameters).Result;

// Extract all file streams to the specified directory

string extractDir = Path.GetTempPath();

foreach (var streamInfo in docResp.StreamsInfo)

{

string extractFileName = Path.Combine(extractDir, streamInfo.FileName);

File.WriteAllBytes(extractFileName, streamInfo.StreamData);

}

Risposta:

Ogni funzione chiamata dal nuovo lavoro di workflow “Chiama funzione” deve restituire alcuni parametri di risposta obbligatori in formato JSON all'interno della risposta HTTP:

•TheError: valore stringa obbligatorio. Se la stringa non è vuota, verrà visualizzata nello storico del workflow. L'istanza sarà contrassegnata come errata, a meno che non venga richiesto un nuovo tentativo in un momento seguente.

•TheRetryAfterMin: valore intero opzionale. Può essere utilizzato per richiedere l'esecuzione di un nuovo tentativo da parte di Therefore™.

Se è impostato su un valore maggiore di zero, il lavoro 'Chiama funzione' funzionerà come un lavoro 'Attendi' e invierà una nuova richiesta una volta trascorso (circa) il numero di minuti specificato. Se "TheError" è impostato, viene trattato come avviso e non contrassegna l'istanza di workflow come errata.

•TheRoutingDone: valore booleano obbligatorio, a meno che non sia stato specificato un valore per "TheRetryAfterMin".

Può essere impostato su 'true' per indicare che l'indirizzamento dell'istanza di workflow è già stato eseguito dalla funzione mediante la funzione Web API 'FinishCurrentWorkflowTask'. Se è impostato su 'false', Therefore™ indirizza l'istanza di workflow al lavoro successivo. Se "TheRetryAfterMin" è specificato, l'indirizzamento non viene eseguito per il momento, quindi in questo caso è facoltativo.

Per semplificare la restituzione di questi parametri, è stata creata la classe “TheRespParams”, che li include tutti sotto forma di proprietà e fornisce la funzione “Serialize” per la creazione di un oggetto JSON.

Sono disponibili due modi per inizializzare un oggetto di questa classe:

•Utilizzando “TheError” e “TheRoutingDone”

TheRespParams respParams = new TheRespParams(errMsg, routingDone);

Deve essere utilizzato come modalità predefinita oppure in caso di errore. Entrambi i valori sono opzionali.

Per impostazione predefinita, errMsg è vuoto e routingDone è false.

•Utilizzando “TheError” e “TheRetryAfterMin”

TheRespParams respParams = new TheRespParams(retryAfterMin, errMsg);

Indica a Therefore™ di effettuare un nuovo tentativo di chiamata della funzione in un secondo momento. Il valore intero retryAfterMin deve essere maggiore di zero; errMsg è facoltativo e e viene registrato come informazione aggiuntiva (non come errore) nello storico del workflow.

Richiesta:

Con ogni chiamata di funzione, Therefore™ invia i parametri seguenti alla funzione come oggetto JSON insieme alla richiesta HTTPS:

•TheWebAPIUrl: contiene l'impostazione server "URL API web", che può essere configurata nella scheda 'XML Web Service' o nelle impostazioni avanzate. Questa impostazione sarà già configurata nel modo corretto se si usa Therefore™ Online, ma può essere lasciata vuota se non è configurata.

•TheTenant: nome del locatario (tenant) corrente. Sarà vuoto se il sistema non utilizza la modalità di multi-locazione.

•TheAccessToken: un token JWT che può essere utilizzato per connettersi a Therefore™ mediante l'API web. Il token è configurato in modo da concedere a "$TheWFSystem" l'accesso utente al documento o al fascicolo associato con l'istanza di workflow corrente, nonché all'istanza di workflow corrente e al token. Con le autorizzazioni concesse è possibile modificare il documento associato, il fascicolo o i documenti associati al fascicolo. Inoltre, le autorizzazioni devono consentire l'indirizzamento dell'istanza di workflow a un altro lavoro. Non è invece possibile creare nuovi documenti o fascicoli, né eseguire query. Non si può nemmeno eliminare il fascicolo o documento principale associato all'istanza di workflow, né l'istanza di workflow stessa.

•TheInstanceNo: numero istanza dell'istanza di workflow corrente.

•TheTokenNo: numero di token dell'istanza di workflow corrente.

•TheCaseNo: numero di fascicolo del fascicolo associato all'istanza di workflow corrente. Questo parametro è disponibile solo per i workflow basati su fascicoli.

•TheDocNo: numero di documento del documento principale associato all'istanza di workflow corrente. Questo parametro è disponibile solo per i workflow basati su documenti.

•TheSettings: oggetto JSON (passato come stringa) di tutte le 'Impostazioni funzione personalizzate' configurate.

Può essere vuoto oppure utilizzato per passare ulteriori parametri alla funzione chiamata. Nome e valore di ogni impostazione possono essere scelti liberamente, ma i nomi devono essere univoci in base alla specifica JSON. Tutti i valori vengono trattati come valori stringa e devono essere convertiti in un altro tipo all'interno della funzione, se richiesto.

Per semplificare la lettura di questi parametri dalla stringa JSON, è stata creata la classe “TheReqParams”, che li include tutti sotto forma di proprietà e fornisce la funzione “Deserialize” per la creazione di un oggetto da una stringa JSON.

Il codice della classe “TheReqParams” può essere utilizzato come esempio per le impostazioni personalizzate dell'utente.

Supponiamo che sia stato configurato “TaskNo” con un valore intero nella configurazione del lavoro di workflow come “impostazione di funzione personalizzata”; per leggerlo, si potrebbe usare la classe seguente:

class CustomSettings

{

public string taskNo;

public int TaskNo

{

get { return int.Parse(taskNo); }

set { taskNo = value.ToString(); }

}

public static CustomSettings Deserialize(string json)

{

return JsonConvert.DeserializeObject<CustomSettings>(json);

}

}

Il codice nel progetto di esempio controllerà principalmente se sono stati specificati nome utente e password, e il token di accesso fornito sarà utilizzato solo come alternativa. In tal modo, il token verrà utilizzato come modalità predefinita solo se non vengono specificati nome utente e password. Queste credenziali possono essere necessarie qualora fossero richieste più autorizzazioni di quelle fornite dal token.

TheConfig.cs usa ConfigurationBuilder per accedere sia a “local.settings.json” che alle variabili di ambiente per cercare la configurazione.

Quando si esegue la funzione Azure localmente, l'impostazione viene letta da “local.settings.json”. Per aggiungere l'impostazione, inserire le impostazioni “WebAPIUser” e “WebAPIPassword” nell'oggetto JSON “Values” come nell'esempio seguente:

{

"IsEncrypted": false,

"Values": {

"AzureWebJobsStorage": "UseDevelopmentStorage=true",

"FUNCTIONS_WORKER_RUNTIME": "dotnet",

"WebAPIUser": "Domain\\TestUser1",

"WebAPIPassword": "secretpassword"

}

}

Quando la funzione è stata distribuita in Azure, le impostazioni vengono lette dalle Impostazioni delle app.

Per aggiungere nome utente e password, selezionare l'App per le funzioni nel portale Azure e fare clic su “Impostazioni applicazione”. Le nuove impostazioni possono essere aggiunte facendo clic su “Nuova impostazione applicazione”.

Al termine fare clic su “Salva”.

Le funzioni Azure possono essere distribuite alla piattaforma Microsoft Azure direttamente da Visual Studio.

Fare clic con il pulsante destro sul progetto, quindi selezionare “Pubblica” per pubblicare la funzione Azure.

Selezionare “App per le funzioni di Azure” per caricarla su Azure direttamente da Visual Studio.

Se si sceglie “Cartella”, la funzione va caricata manualmente tramite FTP.

Il nome dell'App per le funzioni deve essere unico a livello globale, poiché viene creato un piccolo sito web (“https://NomeAppFunzioni.azurewebsites.net”) pubblicamente disponibile, indipendentemente dal fatto che la funzione sia attivabile via HTTP o meno (il trigger HTTP utilizzerà lo stesso URL).

Ogni App per le funzioni di Azure deve avere un Account di archiviazione in cui salvare le funzioni e i registri.

Sono disponibili due diverse opzioni per l'hosting di un'App per le funzioni:

•Piano a consumo
Il piano a consumo assegna automaticamente la potenza di elaborazione quando il codice viene eseguito. La priorità di elaborazione dell'app viene elevata quando è necessario gestire il carico di elaborazione e ridotta quando il codice non è in esecuzione. Non è previsto alcun pagamento per VM inattive e non è necessario prenotare risorse in anticipo.
La fatturazione è basata sul numero di esecuzioni, sul tempo di esecuzione e sulla memoria utilizzata.
Un piano a consumo è indicato per funzioni con tempi di esecuzione limitati. Il tempo di esecuzione massimo predefinito è di 5 minuti e può essere aumentato a 10 minuti. (Note: le funzioni attivate via HTTP prevedono un timeout di 230 secondi indipendentemente dal tempo di esecuzione configurato.)

•Piano di servizio app
Nel piano di servizio app dedicato, le app per le funzioni vengono eseguite su VM dedicate con SKU Basic, Standard, Premium, Isolated, come per le altre app del tipo Servizio app. Le VM dedicate vengono allocate alla app per le funzioni, il che significa che l'host delle funzioni può rimanere sempre in esecuzione.
Una VM scollega i costi dal numero di esecuzioni, dal tempo di esecuzione e dalla quantità di memoria utilizzata. Un piano di servizio app può essere più conveniente se le app per le funzioni vengono eseguite su base continuativa o quasi.

Una volta implementata la funzione, la chiamata genererà un errore 401 “Non autorizzato”.

Per impostazione predefinita, una chiave funzione viene utilizzata per l'autorizzazione da fornire per ogni chiamata.

La chiave può essere ottenuta dal portale Azure.

Dopo aver aperto l'App per le funzioni, fare clic su “Gestione” e copiare la chiave “predefinita”.

Una chiamata da Therefore™ includerà la chiave come “x-functions-key” nell'intestazione di richiesta, se configurata.

Per testare l'esito positivo dell'implementazione senza Therefore™ è possibile usare cURL o un programma analogo.

curl –d “” –i –X POST “https://AppName.azurwebsites.net/api/Route?code=FunctionKey”

Se non viene definito un percorso (route), viene invece utilizzato il nome funzione.