Sana Assistant (online)
Table of Contents

Extension.Api reference

Every extension is created as a class inherited from one of the base extension classes. In turn, every base extension class inherits from Extension abstract class.

For example, core Sana payment extension, which encapsulates Docdata payment service provider, is implemented in DocdataPaymentExtension class, which is inherited from PaymentExtension which, in turn, inherits from Extension class.

Extension classes hierarchy

Extension abstract class provides Api property which holds the instance of SanaApi type and which is the entry point to core Sana Commerce Framework functionality:

public abstract class Extension
{
    public SanaApi Api { get; internal set; }

    ...
}

Api provides access to functionality such as reading or writing files, logging errors, getting Sana texts and messages, etc.

Properties

SanaApi

CheckoutData

Gets the instance of the DataManager type. Provides access to storing and retrieving data scoped to the checkout process, from within extension.

See Extension.Api.CheckoutData reference.

Api.CheckoutData.Save("some data");

CurrentUserData

Gets the instance of the DataManager type. Provides access to storing and retrieving data scoped to the current user, which is kept in SQL database, from within extension.

See Extension.Api.CurrentUserData reference.

Api.CurrentUserData.Save("some data");

DataFiles

Gets the instance of the DataFiles type. Provides access to reading and writing files to extension's isolated file storage.

See Extension.Api.DataFiles reference.

using (var file = Api.DataFiles.OpenRead("somefile.txt"))
{
    ...
}

Products

Gets the instance of the ProductManager type. Provides product retrieving functionality.

See Extension.Api.Products reference.

protected override void Initialize(ProductSetContentBlockModel contentBlock)
{
    var loadOptions = new ProductLoadOptions();
    loadOptions.PageSize = contentBlock.MaximumProductsToShow;
    loadOptions.SortOption = contentBlock.SortOption;
    contentBlock.Products = Api.Products.GetProductsByProductSet(contentBlock.ProductSetId, loadOptions);
}

WebsiteId

Gets the identifier of current web store being browsed by the user during current HTTP request.

string currentWebsiteId = Api.WebsiteId;

NewsletterManager

Gets the instance of the NewsletterManager type. Provides newsletter retrieving functionality.

See Extension.Api.NewsletterManager reference.

Api.NewsletterManager.Subscribe("some@sana-commerce.com");

PackageConfiguration

Gets the the package configuration from the appsettings file.

//Get configuration
var config = Api.PackageConfiguration;

//Read configuration by key 
string value = "";
config.TryGetValue("SomeKey", out value);

KeyValueStorage

Gets the instance of the KeyValueDataStorage type. Provides access to key-value persistent data storage functionality.

See Extension.Api.KeyValueStorage reference.

//Get data from persistent storage
var options = new KeyValueLoadOptions
{
    PageIndex = 0,
    PageSize = 10,
};
var retrievedData = await Api.KeyValueStorage.GetListAsync("Entity1", options);

//Save data to persistent storage
var items = new List<KeyValueData>
{
    new KeyValueData("key1", "value1"),
    new KeyValueData("key2", "value2"),
    new KeyValueData("key3", "value3"),
};
await Api.KeyValueStorage.SaveAsync("Entity1", items);

MailManager

Gets the instance of the MailManager type. Provides mail sending functionality.

See Extension.Api.MailManager reference.

var replacementTags = new NameValueCollection();
replacementTags.Add("LINK", "example.com");
Api.MailManager.SendEmail(new List<string>() { some@sana-commerce.com }, "FollowEmail", replacementTags);

Methods

GetSanaText

Gets Sana text which can be used as a message on user interface for example.

var msg = Api.GetSanaText("CustomTextKey", "This is a default text for this message");

Log

Writes informational message to the log file.

Api.Log("Some informational message");

Writes informational message to the log file with specific arguments.

Api.Log("Some informational message. CustomerId: {CustomerId}", "123");

LogError

Writes error message to the log file.

Api.LogError("An error has just occurred.");

Writes error message to the log file with specific arguments.

Api.LogError("An error has just occurred. CustomerId: {CustomerId}", "123");
Important

Amount of arguments in log message must be equal to amount of arguments passed in log method, otherwise exception will be thrown.

Important

Never write customer's personal data to log files. Names, addresses, phone numbers, etc. must never be written to log files. Also never write payment sensitive data, e.g. payment card data, to log files.

IsShopAccountInSegment

Checks whether account belongs to the specified customer segment.

Api.IsShopAccountInSegment(customerSegmentId, shopAccount);

Profile

Creates new performance profiling step for performance profiler that can be shown on frontend pages.

using (var step = Api.Profile("Profiling extension."))
{
    // profiled code goes here
}

See also