Dinaup SDK (.NET)

El SDK de Dinaup para .NET te permite conectar tus aplicaciones directamente con la plataforma Dinaup.

Dinaup es una plataforma empresarial donde cada empresa tiene su propio conjunto de estructuras de datos, secciones, informes, flujos y documentos dinámicos. Con la librería cliente de .NET (DinaupClient), puedes interactuar con esta plataforma desde tus aplicaciones.

Table of Contents

• Introduction

• Installation

• Getting Started

  • Initialization

  • Session Management

• Core Functionalities

  • Data Operations

    • Adding Records

    • Editing Records

    • Bulk Operations

    • Direct vs. Virtualized Writing

  • File Management

    • Uploading Files

    • Signing URLs

  • Email Sending

  • Annotations

• Advanced Features

  • Working with Dynamic Documents

  • Using Reports

• Error Handling and Debugging

• Best Practices

• Conclusion

• Further Resources

Introduction

Dinaup is a flexible SaaS platform where each company maintains its own data, documents, reports, and structures. The platform utilizes sections (similar to database tables) to store data, dynamic documents (scripts generating plain text documents like HTML, JSON, etc.), and reports (configurable queries akin to PostgreSQL views).

To facilitate interaction with the Dinaup API, we provide a .NET Core client library called DinaupClient. This client is generic and can handle any model or structure auto-generated in MyDinaup, a company-specific library defining models and constants.

Installation

The DinaupClient library is available as a NuGet package hosted on GitHub Packages. To install it, follow these steps:

1. Add the GitHub Package source to your NuGet sources:

   nuget sources Add -Name "GitHub-Dinaup" -Source "https://nuget.pkg.github.com/DinaupSoftware/index.json" -Username YOUR_GITHUB_USERNAME -Password YOUR_GITHUB_TOKEN

   Ensure your GitHub token has the read:packages scope.

2. Install the package in your project:

   Install-Package Dinaup -Version x.x.x

   Replace x.x.x with the latest version.

Note: In the future, the library will also be available on NuGet.org.

Getting Started

Initialization

To start using the DinaupClient, you need to initialize it with the following parameters:

• Endpoint: The API endpoint URL.

• API Key: Your public API key.

• API Secret: Your secret API key.

• Default User ID: (Optional) The user ID for default sessions.

Here's how you can initialize the client:

using Dinaup;

var endpoint = "https://api.dinaup.com";
var apiKey = "YOUR_PUBLIC_API_KEY";
var apiSecret = "YOUR_SECRET_API_KEY";
var defaultUserId = "*"; // Use "*" for system user or provide a GUID for a specific user

var dinaupClient = new DinaupClientC(endpoint, apiKey, apiSecret, defaultUserId);
dinaupClient.Ini();

// Verify the connection
if (dinaupClient.IsConnected)
{
    Console.WriteLine("Connected to Dinaup API successfully.");
}
else
{
    Console.WriteLine("Failed to connect to Dinaup API.");
}

Session Management

DinaupClient requires sessions to perform operations that depend on user context. Sessions can be for the system user or specific users.

Default Session

After initializing the client, you can update the default session:

await dinaupClient.DefaultSessionUpdateAsync();

if (dinaupClient.DefaultSession != null)
{
    Console.WriteLine("Default session initialized.");
}
else
{
    Console.WriteLine("Default session is null.");
}

User Sessions

To create a session for a specific user:

var userEmail = "[e-mail]";
var userPassword = "userpassword";
var userSession = await dinaupClient.Session_SignInAsync(userEmail, userPassword, "DeviceName", "DeviceToken");

if (userSession.Ok)
{
    Console.WriteLine("User session created successfully.");
}
else
{
    Console.WriteLine("Failed to create user session.");
}

Core Functionalities

Data Operations

Dinaup allows you to perform CRUD (Create, Read, Update, Delete) operations on dynamic sections. Each company has its own set of sections defined in MyDinaup, which provides the models and constants.

Adding Records

To add a new record to a section:

1. Using WriteOperation Directly (recommended)

   var data = new Dictionary<string, string>
   {
       { MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, "Sample Text" },
       // Add other fields
   };
   
   var writeOperation = new WriteOperation(string.Empty, data);
   var sectionId = MyDinaup.SectionsD.SeccionDePruebasAPID._SectionIDGUID;
   
   var result = dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, sectionId, writeOperation, false);
   result.EnsureSucess();

2. Using Models (not recommended)

   // Create an instance of the model
   var newRecord = new MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIC
   {
       TextoPrincipal = "Sample Text",
       // Set other fields as needed
   };
   
   // Run the write operation
   var result = dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, newRecord, false);
   result.EnsureSucess();

Editing Records

To edit an existing record:

1. Retrieve the record you want to edit:

   var recordId = Guid.Parse("RECORD_GUID");
   var data = new Dictionary<string, string>
   {
       { MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, "Sample Text" },
       // Add other fields
   };
   
   var writeOperation = new WriteOperation(recordId, data);
   var sectionId = MyDinaup.SectionsD.SeccionDePruebasAPID._SectionIDGUID;
   
   var result = dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, sectionId, writeOperation, false);
   result.EnsureSucess();

Bulk Operations

You can perform bulk operations by providing a list of WriteOperation instances:

var writeOperations = new List<WriteOperation>();

for (int i = 0; i < 100; i++)
{
    var data = new Dictionary<string, string>
    {
        { MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, $"Sample Text {i}" },
        // Add other fields
    };
    var writeOperation = new WriteOperation(string.Empty, data);
    writeOperations.Add(writeOperation);
}

var sectionId = MyDinaup.SectionsD.SeccionDePruebasAPID._SectionIDGUID;
var result = dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, sectionId, writeOperations, false);

if (result.Ok)
{
    Console.WriteLine("Bulk operation completed successfully.");
}
else
{
    Console.WriteLine("Bulk operation failed.");
}

Direct vs. Virtualized Writing

• Direct Writing: Faster but doesn't execute scripts or events.

• Virtualized Writing: Executes scripts and events, automatically recalculates data if required (e.g., calculating totals in a sale).

Specify the writing mode in the RunWriteOperation method:

// Direct Writing
dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, record, false);

// Virtualized Writing
dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, record, true);

File Management

Uploading Files

You can upload files up to 700MB.

Uploading from Bytes

var fileBytes = Encoding.UTF8.GetBytes("File content");
var uploadResult = dinaupClient.File_UploadBytes(dinaupClient.DefaultSession, fileBytes, "filename.txt");

if (uploadResult.FileId != Guid.Empty)
{
    Console.WriteLine("File uploaded successfully. File ID: " + uploadResult.FileId);
}
else
{
    Console.WriteLine("File upload failed.");
}

Uploading from URL

var fileUrl = "https://example.com/image.png";
var uploadResult = dinaupClient.File_UploadURL(dinaupClient.DefaultSession, fileUrl, "image.png");

if (uploadResult.FileId != Guid.Empty)
{
    Console.WriteLine("File uploaded successfully from URL. File ID: " + uploadResult.FileId);
}
else
{
    Console.WriteLine("File upload failed.");
}

Signing URLs

To generate a signed URL for a private file:

var fileId = Guid.Parse("FILE_GUID");
var signedUrl = dinaupClient.File_GetSignedUrl(dinaupClient.DefaultSession, fileId);

Console.WriteLine("Signed URL: " + signedUrl);

Email Sending

To send an email:

var recipient = "[e-mail]";
var subject = "Test Email";
var body = "This is a test email.";

dinaupClient.SendEmail(dinaupClient.DefaultSession, recipient, subject, body);

Console.WriteLine("Email sent successfully.");

Annotations

Annotations allow you to attach notes, files, and participate in chats related to records.

Adding an Annotation

var sectionId = MyDinaup.SectionsD.SeccionDePruebasAPID._SectionIDGUID;
var recordId = "RECORD_ID"; // GUID as string
var annotationText = "This is a comment.";
var annotationType = AnnotationTypeE.Comments; // Or Files, PublicGallery

await dinaupClient.Annotation_PutAsync(dinaupClient.DefaultSession, sectionId, recordId, Guid.Empty, annotationText, annotationType);

Console.WriteLine("Annotation added successfully.");

Retrieving Annotations

var annotationsResult = await dinaupClient.Annotations_GetAsync(dinaupClient.DefaultSession, sectionId, recordId, true, true, true);

foreach (var annotation in annotationsResult.Annotations)
{
    Console.WriteLine($"Annotation: {annotation.Text}");
}

Advanced Features

Working with Dynamic Documents

Dynamic documents are scripts that generate plain text documents (HTML, JSON, XML, etc.).

Executing a Dynamic Document

var dynamicDocumentId = "DOCUMENT_GUID";

// Without parameters
var documentResult = await dinaupClient.DynamicDocuments_ExecuteAsync(dinaupClient.DefaultSession, dynamicDocumentId);

Console.WriteLine("Document Content:");
Console.WriteLine(documentResult.R_DocumentContent);

// With parameters
var parameters = new Dictionary<string, string>
{
    { "ParameterName", "ParameterValue" }
};

var documentResultWithParams = await dinaupClient.DynamicDocuments_ExecuteAsync(dinaupClient.DefaultSession, dynamicDocumentId, parameters);

Console.WriteLine("Document Content with Parameters:");
Console.WriteLine(documentResultWithParams.R_DocumentContent);

Using MyDinaup Models

var documentModel = new MyDinaup.DynamicDocuments.APID.DocumentNameC("ParameterValue");
await documentModel.ExecuteAsync(dinaupClient, dinaupClient.DefaultSession);

Console.WriteLine("Document Content:");
Console.WriteLine(documentModel.Response.R_DocumentContent);

Using Reports

Reports are configurable queries similar to database views.

Executing a Report

var report = new MyDinaup.Reports.FuncionalidadD.APISeccionDePruebasAPIC();
await report.ExecuteQueryAsync(dinaupClient, page: 1, rowsPerPage: 10);

Console.WriteLine("Total Results: " + report.TotalResults);

foreach (var row in report.Rows)
{
    Console.WriteLine($"Record ID: {row.ID}, Text: {row.TextoPrincipal}");
}

Applying Filters

var report = new MyDinaup.Reports.FuncionalidadD.APISeccionDePruebasAPIC();
report.AddFilter(MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIES.ValorEntero, "=", "12");
await report.ExecuteQueryAsync(dinaupClient, page: 1, rowsPerPage: 10);

Console.WriteLine("Filtered Results: " + report.TotalResults);

foreach (var row in report.Rows)
{
    Console.WriteLine($"Record ID: {row.ID}, ValorEntero: {row.Valorentero}");
}

Ordering Results

var report = new MyDinaup.Reports.FuncionalidadD.APISeccionDePruebasAPIC();
report.AddOrderBy(MyDinaup.SectionsD.SeccionDePruebasAPID.SeccionDePruebasAPIES.TextoPrincipal, ascending: true);
await report.ExecuteQueryAsync(dinaupClient, page: 1, rowsPerPage: 10);

foreach (var row in report.Rows)
{
    Console.WriteLine($"Record ID: {row.ID}, Text: {row.TextoPrincipal}");
}

Error Handling and Debugging

When performing operations, it's essential to handle exceptions and check for errors.

Handling Exceptions

try
{
    // Perform an operation
    var result = await dinaupClient.Session_SignInAsync("[e-mail]", "wrongpassword", "DeviceName", "DeviceToken");
}
catch (Exception ex)
{
    Console.WriteLine("An error occurred: " + ex.Message);
}

Checking Operation Results

var result = dinaupClient.RunWriteOperation(dinaupClient.DefaultSession, record, false);

if (result.Ok && result.Results.Values.First().Confirmed)
{
    Console.WriteLine("Operation succeeded.");
}
else
{
    Console.WriteLine("Operation failed.");
    foreach (var error in result.Results.Values.First().Errors)
    {
        Console.WriteLine("Error: " + error);
    }
}