If you want to export data in a particular format, then the export framework can provide you preprocessed data through the
IExportProvider interface. The export provider just defines how to format the data. All the rest is done by the export framework. The merchant selects your provider when he creates an export profile. The export profile is a plan that defines all aspects of an export such as data partitioning, filtering, projection, configuration, deployment etc.
If you are not familiar with developing plugins for SmartStore.NET, please also have look at the tutorial How to write a Plugin.
The IExportProvider interface
The first step in your plugin is to create an export provider class that inherits from
ExportProviderBase or directly implements
IExportProvider. Decorate the class with the
SystemName attribute and optionally with
DisplayOrder. We suggest prefixing the system name with
The rarely used
IsHidden attribute hides the provider so that it cannot be selected by the merchant (when creating an export profile).
ExportFeatures attribute allows you to control the data processing, the provided data and the projection of an export profile. It is an enumeration with the following bitwise OR-combined values:
- None: There are no features supported by the provider.
- CreatesInitialPublicDeployment: Whether to automatically create a file based public deployment when an export profile is created.
- CanOmitGroupedProducts: Whether to offer option to include/exclude grouped products.
- CanProjectAttributeCombinations: Whether to offer option to export attribute combinations as products.
- CanProjectDescription: Whether to offer further options to manipulate the product description.
- OfferBrandFallback: Whether to offer option to enter a brand fallback.
- CanIncludeMainPicture: Whether to offer option to set a picture size and to get the URL of the main image.
- UsesSkuAsMpnFallback: Whether to use SKU as manufacturer part number if MPN is empty.
- OffersShippingTimeFallback: Whether to offer option to enter a shipping time fallback.
- OffersShippingCostsFallback: Whether to offer option to enter a shipping costs fallback and a free shipping threshold
- UsesOldPrice: Whether to get the calculated old product price.
- UsesSpecialPrice: Whether to get the calculated special and regular (ignoring special offers) price.
- CanOmitCompletionMail: Whether to automatically send a notification email about the completion of an export task.
The next step is to override the properties and methods of
IExportProvider for you.
- EntityType (property): Specifies the entity type to be exported. Current Product, Category, Manufacturer, Customer, Order and NewsLetterSubscription are available. Product is the default.
- FileExtension (property): Specifies the file extension (without dot) of the export file(s). Return
nullfor a non file based, on-the-fly export.
- ConfigurationInfo (property): Specifies information about a partial view that is embedded in the profile edit page containing your provider specific configuration data. Return
nullwhen no provider specific configuration is required.
- Export (method): Called to export data into a file. The
IExportExecuteContextparameter provides all required information. More on this later.
- OnExecuted (method): Called after the data of one store has been exported.
The above example shows the main part of the Google Merchant Center product feed export provider. The item processing statements have been removed for the sake of clarity. You can find them on GitHub.
ConfigurationInfo and ConfigurationData
The ConfigurationInfo property tells the export framework where to find the partial view with the provider specific configuration, the type of the view model and the optional callback called to initialize a view model instance. If your provider does not require any configuration, simply return
null for ConfigurationInfo. Partial view and its view model lie in your plugin, but the view is automatically embedded in a tab in the profile edit page. Therefore, the merchant can configure your provider for each profile separately and does not have to leave the profile edit page to do so. In the above example, the view model instance is initialized with a list of all available Google categories. If your view model does not require any initialization, simply return
null for Initialize.
ConfigurationData is a property of type
object. You can cast it to your view model type to get access to the configuration values stored together with the export profile.
Export method and IExportExecuteContext parameter
This is the main routine where all the provider specific data formatting happens. The Export method is called once or multiple times per store, depending on how the merchant configured the partitioning.
IExportExecuteContext.DataStream gives you the stream object to be used for writing the export data. Properties and methods of IExportExecuteContext:
- Segmenter: The data segementer that provides the data to be exported. Typicallly used like in the above sample.
- Store: Dynamic property which represents the store context for the export.
- Customer: Dynamic property which represents the customer context for the export.
- Currency: Dynamic property which represents the currency context for the export.
- Language: Dynamic property which represents the language context for the export.
- Projection: Projection settings for the export.
- Log: The file logger instance to be used for any log information.
- Abort: Property that indicates an abortion of the export.
ExportAbortion.Nonemeans no abortion,
ExportAbortion.Softmeans breaking the entity processing but not the rest of the execution (typically used for demo mode limitations) and
ExportAbortion.Hardmeans breaking the processing immediately.
- DataStreamId: Identifier of current data stream. Can be
- DataStream: Stream used to write data to.
- ExtraDataStreams: List with extra data streams required by provider.
- MaxFileNameLength: The maximum length for export file names.
- Folder: The path of the export content folder.
- FileName: The name of the current export file.
- HasPublicDeployment: Whether the profile has a public deployment into the
Exchangefolder of the store.
- PublicFolderPath: The local path to the public
Exchangefolder of the store. It is
nullif the profile has no public deployment.
- PublicFileUrl: The public URL of the export file (accessible through the internet). It is
nullif the profile has no public deployment.
- ConfigurationData: Property of type
objectwith provider specific configuration data.
- CustomProperties: Use this dictionary for any custom data required along the whole export\profile execution.
- RecordsSucceeded: Number of successful processed records.
- RecordsFailed: Number of failed records.
- RecordException: Method (helper) that processes an exception that occurred while exporting a single record (see above example).
Data provided as dynamic objects
IExportExecuteContext provides entity related data as dynamic objects. The property names of the dynamic object and the entity are always equal. One big advantage of dynamic objects is that they can be extended by compound data. Compound properties of
IExportExecuteContext always begin with an underline to avoid conflicts with property names of the entity. For example, the
dynamic product in the above sample might look like this during run-time:
_MainPictureUrl, for instance, is not an entity property. It is a computed value attached to the dynamic product object. Some compound properties are only provided if the corresponding
ExportFeatures value is set. Other compound properties such as
product._DetailUrl are always attached. The property
Entity, for instance, gives you access to the underlying original entity object and is attached to each dynamic object.