How to: Create Providers for PerformancePoint Services Tabular Data Source
Data source providers connect to a data source, access its data, and then return query results. PerformancePoint Services in Microsoft SharePoint Server 2010 uses tabular data source providers to access data from Microsoft Excel and Excel Services worksheets, SharePoint lists, and Microsoft SQL Server tables.
Applies to: SharePoint Server 2010
You can create a custom data source provider to use data from a tabular data source that is not supported by PerformancePoint Services. The main function of a tabular data source provider is to create and populate a data table with data from the data source. It also creates column mappings to define the type of data that each column contains (fact, dimension, or time dimension). This applies a basic multidimensional structure to the tabular data.
The procedures and code examples in this topic are based on the WSTabularDataSourceProvider class from the custom objects sample. The provider retrieves stock quotes from an external Web service for specified stock symbols. It stores historical stock quote data in a cache file, which enables the data to be sliced by time. The complete code for the class is provided in the "Example" section in this topic.
Note
We recommend that you use the sample data source provider as a template. The sample shows how to call objects in the PerformancePoint Services API and demonstrates best practices for PerformancePoint Services development.
You create a data source provider by performing two basic procedures, as follows:
Creating and configuring the provider class
Defining the provider functionality
To create a custom provider, start by creating the provider class.
To create and configure the provider class
Install PerformancePoint Services, or copy the DLLs that your extension uses (listed in step 3) to your computer. For instructions, see PerformancePoint Services DLLs Used in Development Scenarios.
In Visual Studio, create a C# class library. If you have already created a class library for your extension, add a new C# class.
Add the following PerformancePoint Services DLLs as assembly references to the project:
Microsoft.PerformancePoint.Scorecards.Client.dll
Microsoft.PerformancePoint.Scorecards.DataSourceProviders.Standard.dll
The sample data source provider also contains assembly references to System.Core.dll, System.ServiceModel.dll, System.Web.dll, System.Web.Services.dll, and System.Xml.Linq.dll. Depending on your extension's functionality, other project references may be required.
Add a service reference named StockQuotes that references the Web service located at the address http://www.webservicex.net/stockquote.asmx. This is the Web service that provides stock quotes for the sample data source.
Add the BasicTabularDataSourceProvider and SampleDSCacheHandler classes from the sample to your project. BasicTabularDataSourceProvider inherits from the TabularDataSourceProvider class, which is the base class for tabular data source providers.
The sample data source also uses the class as a container for the overridden abstract methods that TabularDataSourceProvider does not implement (GetDatabaseNames(), GetCubeNames(), GetCubeNameInfos(), GetCubeMetaData, and Validate()).
In your provider class, add using directives for the following PerformancePoint Services namespaces:
Microsoft.PerformancePoint.SDK.Samples.StockQuotes (represents the StockQuotes service reference created in step 4)
Depending on your extension's functionality, other using directives may be required.
Inherit from the BasicTabularDataSourceProvider class.
After you create and configure the provider class, you must define your provider’s functionality.
To define the provider functionality
Declare variables and define properties that are used for parsing, storing, and retrieving stock symbols, the cache file location, and the URI of the proxy server.
Override the IsConnectionStringSecure property. This property is not used by PerformancePoint Services, but it is intended for custom applications to optionally use to identify whether a connection string exposes information that might pose a security risk.
Return true if your extension stores sensitive information—such as a user name or password—in the connection string for your data source. Return false if it does not store sensitive information or if your data source does not use a connection string.
Override the GetId() method to return the unique identifier for your provider. GetId() must return the same string as the key attribute that is registered in the PerformancePoint Services web.config file for the custom data source provider.
Override the SetDataSource method to define column mappings. SetDataSource calls the CreateDataColumnMappings method to define data source columns as Fact, Dimension, and TimeDimension types.
SetDataSource also retrieves the stock symbols, cache file location, and proxy server address from the CustomData property of the custom data source object. These values are defined by dashboard authors in the sample data source editor.
Override the GetDataSet() method to create a DataSet object to store the data from the data source. The sample data source provider uses the FillResultsTable and GetLiveQuote methods to populate a data table with data from a Web service.
Next step: After you create a data source provider and a data source editor (including its user interface, if required), deploy the extension as described in How to: Manually Register PerformancePoint Services Extensions. For instructions about how to install the sample data source extension, see the "Installing the Sample Report, Filter, and Data Source Objects" section in PerformancePoint Services Code Sample: Custom Report, Filter, and Tabular Data Source Objects.
Example
The class in the following code example creates a tabular data source provider that retrieves stock quotes from an external Web service and then transforms the data into a tabular format.
Note
Before you can compile this code example, you must configure your development environment as described in To create and configure the provider class.
using System;
using System.Data;
using System.IO;
using System.Linq;
using System.Xml.Linq;
using Microsoft.PerformancePoint.Scorecards;
using Microsoft.PerformancePoint.Scorecards.ServerCommon;
using Microsoft.PerformancePoint.SDK.Samples.StockQuotes;
using System.ServiceModel;
namespace Microsoft.PerformancePoint.SDK.Samples.SampleDataSource
{
// Represents the class that defines the sample data source provider.
// It inherits from the BasicTabularDataSourceProvider class, which
// contains overridden abstract methods that are not implemented.
public class WSTabularDataSourceProvider : BasicTabularDataSourceProvider
{
#region Constants
private const int StockSymbolsIndex = 0;
private const int CacheFileLocationIndex = 1;
private const int ProxyAddressIndex = 2;
#endregion
#region Properties
// This property stores the stock symbols that are used
// to query the Web service.
// Its value is obtained by parsing the CustomData property
// of the data source object.
private string[] StockSymbols
{
get;
set;
}
// The address of the proxy server.
private Uri ProxyAddress
{
get;
set;
}
// This property is not used by PerformancePoint Services.
// Its intended use is for custom applications to indicate
// whether a provider stores sensitive information in the
// connection string, such as user name and password.
// This sample does not, so it returns false.
public override bool IsConnectionStringSecure
{
get { return false; }
}
#endregion
#region Overridden methods
// The source name for your data source. This value must match the key
// attribute that is registered in the web.config file.
public override string GetId()
{
return "WSTabularDataSource";
}
// Add column mappings for the sample columns if they do not exist.
// Column mappings may be missing if the custom data source has never
// been edited or if the workspace was not refreshed, which saves
// changes to the server.
public override void SetDataSource(DataSource dataSource)
{
base.SetDataSource(dataSource);
// Check for symbols stored in the CustomData
// property of the data source.
if (null == dataSource ||
string.IsNullOrEmpty(dataSource.CustomData))
{
// Create a symbol for testing purposes.
StockSymbols = new[] { "MSFT" };
}
else
{
string[] splitCustomData = dataSource.CustomData.Split('&');
if (splitCustomData.Length > 2)
{
StockSymbols = splitCustomData[StockSymbolsIndex].ToUpper().Split(',');
for (int iLoop = 0; iLoop < StockSymbols.Length; iLoop++)
{
StockSymbols[iLoop] = StockSymbols[iLoop].Trim();
}
SampleDSCacheHandler.CacheFileLocation = splitCustomData[CacheFileLocationIndex];
ProxyAddress = new Uri(splitCustomData[ProxyAddressIndex]);
}
}
// Check whether column mappings exist. Do not overwrite them.
if (dataSource.DataTableMapping.ColumnMappings.Count == 0)
{
dataSource.DataTableMapping = CreateDataColumnMappings();
}
}
// Get the data from the data source.
// GetDataSet contains the core logic for the provider.
public override DataSet GetDataSet()
{
// Create a dataset and a data table to store the data.
DataSet resultSet = new DataSet();
DataTable resultTable = resultSet.Tables.Add();
// Define column names and the type of data that they contain.
resultTable.Columns.Add("Symbol", typeof(string));
resultTable.Columns.Add("Value", typeof(float));
resultTable.Columns.Add("P-E Ratio", typeof(float));
resultTable.Columns.Add("Percentage Change", typeof(float));
resultTable.Columns.Add("Date", typeof(DateTime));
FillResultTable(ref resultTable);
return resultSet;
}
#endregion
#region Internal methods
// Fill the data table with the stock quote values from
// the Web service and local cache file.
protected void FillResultTable(ref DataTable resultsTable)
{
// Check the sematic validity of symbols (out of scope for this sample).
if (null != StockSymbols &&
StockSymbols.Length > 0 &&
!string.IsNullOrEmpty(SampleDSCacheHandler.CacheFileLocation))
{
try
{
if (!File.Exists(SampleDSCacheHandler.CacheFileLocation))
{
// Create the cache file.
XDocument doc = SampleDSCacheHandler.DefaultCacheFileContent;
doc.Save(@SampleDSCacheHandler.CacheFileLocation);
}
// Get real-time quotes and update cache file.
string wsResult = GetLiveQuote();
SampleDSCacheHandler.UpdateXMLCacheFile(wsResult);
// Check if a valid cache file location exists.
if (SampleDSCacheHandler.CacheFileContent != null)
{
var query = from c in SampleDSCacheHandler.CacheFileContent.Elements("StockQuotes").Elements("StockQuote")
where StockSymbols.Contains(c.Attribute("Symbol").Value)
select c;
foreach (var stockQuote in query)
{
DataRow row = resultsTable.NewRow();
row["Symbol"] = stockQuote.Attribute("Symbol").Value;
row["Value"] = stockQuote.Element("Value").Value;
row["Percentage Change"] = stockQuote.Element("PercentageChange").Value;
row["Date"] = stockQuote.Element("Date").Value;
decimal peRatio;
// Handle symbols that return 'N/A' for this field.
if (decimal.TryParse(stockQuote.Element("PERatio").Value, out peRatio))
{
row["P-E Ratio"] = peRatio;
}
resultsTable.Rows.Add(row);
}
}
}
catch (Exception ex)
{
ServerUtils.HandleException(ex);
}
}
}
// Get real-time quotes from the Web service.
protected string GetLiveQuote()
{
EndpointAddress endpoint = new EndpointAddress("http://www.webservicex.net/stockquote.asmx");
BasicHttpBinding binding = new BasicHttpBinding();
binding.ReceiveTimeout = new TimeSpan(0, 0, 120);
binding.ProxyAddress = ProxyAddress;
binding.UseDefaultWebProxy = false;
StockQuotes.StockQuoteSoapClient wsStockQuoteService = new StockQuoteSoapClient(binding, endpoint);
// Check the sematic validity of symbols (out of scope for this sample).
if (null != StockSymbols &&
StockSymbols.Length > 0)
{
try
{
string quoteRequest = StockSymbols[0];
for (int iLoop = 1; iLoop < StockSymbols.Length; iLoop++)
{
quoteRequest = string.Format("{0}, {1}", quoteRequest, StockSymbols[iLoop]);
}
string wsResult = wsStockQuoteService.GetQuote(quoteRequest);
return wsResult;
}
catch (Exception ex)
{
ServerUtils.HandleException(ex);
}
}
return string.Empty;
}
// Create the column mappings.
internal static DataTableMapping CreateDataColumnMappings()
{
DataTableMapping dtTableMapping = new DataTableMapping();
// Define the data in the Symbol column as dimension data.
dtTableMapping.ColumnMappings.Add(new DataColumnMapping
{
SourceColumnName = "Symbol",
FriendlyColumnName = "Symbol",
UniqueName = "Symbol",
ColumnType = MappedColumnTypes.Dimension,
FactAggregation = FactAggregations.None,
ColumnDataType = MappedColumnDataTypes.String
});
// Define the data in the Value column as fact data.
dtTableMapping.ColumnMappings.Add(new DataColumnMapping
{
SourceColumnName = "Value",
FriendlyColumnName = "Value",
UniqueName = "Value",
ColumnType = MappedColumnTypes.Fact,
FactAggregation = FactAggregations.Average,
ColumnDataType = MappedColumnDataTypes.Number
});
// Define the data in the P-E Ratio column as fact data.
dtTableMapping.ColumnMappings.Add(new DataColumnMapping
{
SourceColumnName = "P-E Ratio",
FriendlyColumnName = "P-E Ratio",
UniqueName = "P-E Ratio",
ColumnType = MappedColumnTypes.Fact,
FactAggregation = FactAggregations.Average,
ColumnDataType = MappedColumnDataTypes.Number
});
// Define the data in the Percentage Change column as fact data.
dtTableMapping.ColumnMappings.Add(new DataColumnMapping
{
SourceColumnName = "Percentage Change",
FriendlyColumnName = "Percentage Change",
UniqueName = "Percentage Change",
ColumnType = MappedColumnTypes.Fact,
FactAggregation = FactAggregations.Average,
ColumnDataType = MappedColumnDataTypes.Number
});
// Define the Date column as a time dimension.
dtTableMapping.ColumnMappings.Add(new DataColumnMapping
{
SourceColumnName = "Date",
FriendlyColumnName = "Date",
UniqueName = "Date",
ColumnType = MappedColumnTypes.TimeDimension,
FactAggregation = FactAggregations.None,
ColumnDataType = MappedColumnDataTypes.DateTime
});
// Increase the granularity of the time dimension.
dtTableMapping.DateAggregationType |= DateAggregationTypes.Quarter;
dtTableMapping.DateAggregationType |= DateAggregationTypes.Month;
dtTableMapping.DateAggregationType |= DateAggregationTypes.Week;
dtTableMapping.DateAggregationType |= DateAggregationTypes.Day;
return dtTableMapping;
}
#endregion
}
}
Compiling the Code
Before you can compile this code example, you must configure your development environment as described in To create and configure the provider class.
Security
You must sign your DLL with a strong name. In addition, ensure that all assemblies referenced by your DLL have strong names. For information about how to sign an assembly with a strong name and how to create a public/private key pair, see How to: Create a Public/Private Key Pair.
See Also
Tasks
How to: Create Editors for PerformancePoint Services Tabular Data Sources
Other Resources
Create Custom Objects for PerformancePoint Services
Code Samples for PerformancePoint Services in SharePoint Server 2010