Dinaup .NET Client Library Documentation

Welcome to the comprehensive guide on using the Dinaup .NET Client Library. This documentation is designed to help developers integrate and interact with the Dinaup API seamlessly using the provided .NET client library.

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:

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.
Install the package in your project:
Install-Package Dinaup -Version x.x.x
Replace x.x.x with the latest version.

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 = "[email protected]"; 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:

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();
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:

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 = "[email protected]"; 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("[email protected]", "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);
    }
}

Best Practices

Initialize the Client Properly: Always call Ini() after creating an instance of DinaupClientC.
Check Connections: Verify IsConnected before performing operations.
Manage Sessions Carefully: Ensure sessions are updated and valid.
Handle Exceptions: Wrap operations in try-catch blocks and handle exceptions gracefully.
Use Models from MyDinaup: Utilize the auto-generated models for your company's sections to simplify data handling.
Limit Bulk Operations: When performing bulk operations, avoid exceeding limits (e.g., avoid sending too many records at once).
Secure API Keys: Never expose your API keys in code repositories or logs.

Conclusion

The Dinaup .NET Client Library provides a robust and flexible way to interact with the Dinaup API, allowing you to manage data, files, emails, and more within your applications. By leveraging the auto-generated models from MyDinaup, you can streamline your development process and focus on building features that add value to your business.

Further Resources

Dinaup GitHub Repository: DinaupSoftware/Dinaup
NuGet Package: Available via GitHub Packages (soon on NuGet.org)
API Documentation: (Provide a link to the official API documentation if available)
Support: Contact Dinaup support for assistance or further information.

Note: This documentation is based on the provided unit tests and examples. For specific use cases or advanced scenarios, refer to the official API documentation or contact support.

Last modified: 04 February 2025

Dinaup - Base de Conocimientos Help