Pandatech.Communicator 1.0.2

There is a newer version of this package available.
See the version list below for details.
dotnet add package Pandatech.Communicator --version 1.0.2
NuGet\Install-Package Pandatech.Communicator -Version 1.0.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Pandatech.Communicator" Version="1.0.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Pandatech.Communicator --version 1.0.2
#r "nuget: Pandatech.Communicator, 1.0.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Pandatech.Communicator as a Cake Addin
#addin nuget:?package=Pandatech.Communicator&version=1.0.2

// Install Pandatech.Communicator as a Cake Tool
#tool nuget:?package=Pandatech.Communicator&version=1.0.2

1. PandaTech.Communicator

1.1. Introduction

PandaTech.Communicator is aimed to send Email and SMS messages to the clients of your service where you use this library.

  • Email: By given setup it's easy and fast to configure and setup Email providers for later use by different channels.
  • SMS: By given setup it's easy and fast to configure and setup already integrated SMS providers for later use by different channels.
    • Dexatel
    • Twilio

This package is ideal for efficient and reliable messaging in any application.

1.2. Installation

Install this NuGet library directly from the IDE package installer or by following command:

dotnet add package PandaTech.Communicator

1.3. Setup

To incorporate PandaTech.Communicator into your project, you have 2 primary methods to setup in your Program.cs:

The first method directly using WebApplicationBuilder from which IConfiguration is directly used. But for the second method builder is not accessible, so we pass IConfiguration into it as parameter.

  • builder.AddCommunicator();
  • services.AddCommunicator(configuration);

Configuration options can be specified either in appsettings.json or directly in Program.cs, with the latter taking precedence.

There are several supported channels which must be kept during setup:

EmailChannels
{
    "GeneralSender",
    "TransactionalSender",
    "NotificationSender",
    "MarketingSender",
    "SupportSender"
};
    
SmsChannels
{
    "GeneralSender",
    "TransactionalSender",
    "NotificationSender",
    "MarketingSender",
    "SupportSender"
};

For each channel can be setup same provider, but it's recommended to have different sender, as they are dedicated for different purposes.

1.3.1. Program.cs Example

In case of using SSL by setting UseSsl = true use port number 456, otherwise use 587 for non SSL connection.

1.3.1.1. Using WebApplicationBuilder
builder.AddCommunicator(options =>
{
    options.SmsFake = false;
    options.SmsConfigurations = new Dictionary<string, SmsConfiguration>
    {
        {
            "GeneralSender", new SmsConfiguration
            {
                Provider = "Dexatel",
                From = "sender_name",
                Properties = new Dictionary<string, string>
                {
                    { "X-Dexatel-Key", "key" }
                },
                TimeoutMs = 10000
            }
        },
        {
            "TransactionalSender", new SmsConfiguration
            {
                Provider = "Twilio",
                From = "sender_number",
                Properties = new Dictionary<string, string>
                {
                    { "SID", "key" },
                    { "AUTH_TOKEN", "token" }
                },
                TimeoutMs = 10000
            }
        }
    };
    options.EmailFake = false;
    options.EmailConfigurations = new Dictionary<string, EmailConfiguration>
    {
        {
            "GeneralSender", new EmailConfiguration
            {
                SmtpServer = "smtp.test.com",
                SmtpPort = 465, // 587
                SmtpUsername = "test",
                SmtpPassword = "test123",
                SenderEmail = "test@test.com",
                UseSsl = true, // false
                TimeoutMs = 10000
            }
        },
        {
            "TransactionalSender", new EmailConfiguration
            {
                SmtpServer = "smtp.gmail.com",
                SmtpPort = 465, // 587
                SmtpUsername = "vazgen",
                SmtpPassword = "vazgen123",
                SenderEmail = "vazgencho@gmail.com",
                UseSsl = true, // false
                TimeoutMs = 10000
            }
        }
    };
});

1.3.1.2. Using IServiceCollection
services.AddCommunicator(configuration, options =>
{
    options.SmsFake = false;
    options.SmsConfigurations = new Dictionary<string, SmsConfiguration>
    {
        {
            "GeneralSender", new SmsConfiguration
            {
                Provider = "Dexatel",
                From = "sender_name",
                Properties = new Dictionary<string, string>
                {
                    { "X-Dexatel-Key", "key" }
                },
                TimeoutMs = 10000
            }
        },
        {
            "TransactionalSender", new SmsConfiguration
            {
                Provider = "Twilio",
                From = "sender_number",
                Properties = new Dictionary<string, string>
                {
                    { "SID", "key" },
                    { "AUTH_TOKEN", "token" }
                },
                TimeoutMs = 10000
            }
        }
    };
    options.EmailFake = false;
    options.EmailConfigurations = new Dictionary<string, EmailConfiguration>
    {
        {
            "GeneralSender", new EmailConfiguration
            {
                SmtpServer = "smtp.test.com",
                SmtpPort = 465, // 587
                SmtpUsername = "test",
                SmtpPassword = "test123",
                SenderEmail = "test@test.com",
                UseSsl = true, // false
                TimeoutMs = 10000
            }
        },
        {
            "TransactionalSender", new EmailConfiguration
            {
                SmtpServer = "smtp.gmail.com",
                SmtpPort = 465, // 587
                SmtpUsername = "vazgen",
                SmtpPassword = "vazgen123",
                SenderEmail = "vazgencho@gmail.com",
                UseSsl = true, // false
                TimeoutMs = 10000
            }
        }
    };
});

1.3.2. Appsettings.json Example

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Communicator": {
    "SmsFake": false,
    "SmsConfigurations": {
      "GeneralSender": {
        "Provider": "Dexatel",
        "From": "sender_name",
        "Properties": {
          "X-Dexatel-Key": "key"
        },
        "TimeoutMs": "10000"
      },
      "TransactionalSender": {
        "Provider": "Twilio",
        "From": "sender_number",
        "Properties": {
          "SID": "key",
          "AUTH_TOKEN": "token"
        },
        "TimeoutMs": "10000"
      }
    },
    "EmailFake": false,
    "EmailConfigurations": {
      "GeneralSender": {
        "SmtpServer": "smtp.gmail.com",
        "SmtpPort": 465, // 587
        "SmtpUsername": "vazgen",
        "SmtpPassword": "vazgen123",
        "SenderEmail": "vazgencho@gmail.com",
        "UseSsl": true, // false
        "TimeoutMs": "10000"
      },
      "TransactionalSender": {
        "SmtpServer": "smtp.gmail.com",
        "SmtpPort": 465, // 587
        "SmtpUsername": "vazgen",
        "SmtpPassword": "vazgen123",
        "SenderEmail": "vazgencho@gmail.com",
        "UseSsl": true, // false
        "TimeoutMs": "10000"
      }
    }
  }
}

The configuration options in appsettings.json and program.cs (priority) are identical.

1.4. Configuration Options Explained

  • Communicator: Global settings for PandaTech.Communicator
  • SmsFake: This setup is for fake SMS service to be used which doesn't send real SMS messages and just return TTask.CompletedTask.
  • SmsConfigurations: SMS configurations given by appsettings.json or via builder.AddCommunicator() options for SMS.
  • EmailFake: This setup is for fake Email service to be used which doesn't send real SMS messages and just return TTask.CompletedTask.
  • EmailConfigurations: Email configurations given by appsettings.json or via builder.AddCommunicator() options for Email.

1.5. Usage

In order to use the library, you need to generate SmsMessage or EmailMessage and use one of the interfaces mentioned above for the service you need to use.

Both of them support multiple recipients.

The structure of the messages are shown below.

public class SmsMessage
{
    public List<string> Recipients { get; set; } = null!;
    public string Message { get; set; } = null!;
    public string Channel { get; set; } = null!;
}

public class EmailMessage
{
    public List<string> Recipients { get; set; } = null!;
    public string Subject { get; set; } = null!;
    public string Body { get; set; } = null!;
    public List<string> Cc { get; set; } = [];
    public List<string> Bcc { get; set; } = [];
    public List<EmailAttachment> Attachments { get; set; } = [];
    public bool IsBodyHtml { get; set; } = false;
    public string Channel { get; set; } = null!;
}

Channel is set by EmailChannels or by SmsChannels classes with constant values.

There are 2 interfaces ISmsService and IEmailService responsible for individual cases SMS or Email. Methods for sending SMS/Email messages are:

  • SendAsync:
  • SendBulkAsync:

The structure of the service interfaces are shown below.

public interface ISmsService
{
    Task<List<GeneralSmsResponse>> SendAsync(SmsMessage smsMessage, CancellationToken cancellationToken = default);
    Task<List<GeneralSmsResponse>> SendBulkAsync(List<SmsMessage> smsMessageList, CancellationToken cancellationToken = default);
}

public interface IEmailService
{
    Task<GeneralEmailResponse> SendAsync(EmailMessage emailMessage, CancellationToken cancellationToken = default);
    Task<List<GeneralEmailResponse>> SendBulkAsync(List<EmailMessage> emailMessages, CancellationToken cancellationToken = default);
}

1.5.1. Send SMS message

var sms = new SmsMessage
{
    Recipients = ["+37493910593"],
    Message = "123456",
    Channel = SmsChannels.GeneralSender
};
await smsService.SendAsync(sms);

Sms service returns general response which includes general properties in already integrated services.

Both methods return List<GeneralSmsResponse> when you use them while sending sms. If you set a variable to the call, you will be able to use returned response.

public class GeneralSmsResponse
{
    public string From { get; set; } = null!;
    public string To { get; set; } = null!;
    public string OuterSmsId { get; set; } = null!;
    public string Status { get; set; } = null!;
    public DateTime CreateDate { get; set; }
    public DateTime UpdateDate { get; set; }
    public string Body { get; set; } = null!;
}

1.5.2. Send Email message

var email = new EmailMessage
{
    Recipients = ["a@a.com"],
    Subject = "Some subject",
    Body = "Some body",
    IsBodyHtml = false,
    Channel = EmailChannels.GeneralSender
};
await emailService.SendAsync(email);

Both methods return response (SendAsync - GeneralEmailResponse; SendBulkAsync - List<GeneralEmailResponse>) when you use them while sending email. If you set a variable to the call, you will be able to use returned response.

public class GeneralEmailResponse
{
    public string Status { get; set; } = null!;
    public string Code { get; set; } = null!;
    public string TrackingId { get; set; } = null!;
    public string Id { get; set; } = null!;
    public string Service { get; set; } = null!;
}

1.6. Limitations

PandaTech.Communicator works with all Email providers, but with only with existing integrations for SMS listed above.

1.7. License

PandaTech.Communicator is licensed under the MIT License.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.3 66 4/17/2024
1.0.2 139 2/23/2024
1.0.1 91 2/23/2024
1.0.0 92 2/23/2024
0.0.1 107 2/8/2024

InitialCommit - fake functionalities