Export ribbon definitions
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
To effectively define changes to the default RibbonXml, you must be able to reference the RibbonXml data that defines those ribbons.
Access the ribbon definitions for your organization
If the Ribbon for your organization has been modified, you should export the current definitions if you intend to work with the customized ribbon elements. To do this, use the exportribbonxml sample located at SampleCode\CS\Client\Ribbon\ExportRibbonXml.
Access the default ribbon data
The default ribbon definitions for Microsoft Dynamics 365 can be found in the SDK package: SDK\Resources\ExportedRibbonXml. Download the Microsoft Dynamics CRM SDK package.
The applicationRibbon.xml file contains the definition of the core application ribbons.
The remaining files contain the definitions used by entities that have ribbon definitions that differ from the entity template. Each file is named according to the name of the entity: logical entity name + Ribbon.xml.
These files represent the output of two messages using the Sample: Export ribbon definitions:
RetrieveApplicationRibbonRequest
This message retrieves the core application ribbons including the entity template.RetrieveEntityRibbonRequest
This message retrieves the ribbon definition used for a specific entity.
Decompress the ribbon data
The ribbon data is exported as a compressed file. To decompress the file into XML you have to use the System.IO.Packaging.ZipPackage class. The following example is a helper method used in the SDK sample to decompress the file.
/// <summary>
/// A helper method that decompresses the the Ribbon data returned
/// </summary>
/// <param name="data">The compressed ribbon data</param>
/// <returns></returns>
public byte[] unzipRibbon(byte[] data)
{
System.IO.Packaging.ZipPackage package = null;
MemoryStream memStream = null;
memStream = new MemoryStream();
memStream.Write(data, 0, data.Length);
package = (ZipPackage)ZipPackage.Open(memStream, FileMode.Open);
ZipPackagePart part = (ZipPackagePart)package.GetPart(new Uri("/RibbonXml.xml", UriKind.Relative));
using (Stream strm = part.GetStream())
{
long len = strm.Length;
byte[] buff = new byte[len];
strm.Read(buff, 0, (int)len);
return buff;
}
}
''' <summary>
''' A helper method that decompresses the the Ribbon data returned
''' </summary>
''' <param name="data">The compressed ribbon data</param>
''' <returns></returns>
Public Function unzipRibbon(ByVal data() As Byte) As Byte()
Dim package As System.IO.Packaging.ZipPackage = Nothing
Dim memStream As MemoryStream = Nothing
memStream = New MemoryStream()
memStream.Write(data, 0, data.Length)
package = CType(ZipPackage.Open(memStream, FileMode.Open), ZipPackage)
Dim part As ZipPackagePart = CType(package.GetPart(New Uri("/RibbonXml.xml", UriKind.Relative)), ZipPackagePart)
Using strm As Stream = part.GetStream()
Dim len As Long = strm.Length
Dim buff(CInt(len - 1)) As Byte
strm.Read(buff, 0, CInt(len))
Return buff
End Using
End Function
Retrieve the application ribbon data
The application ribbon can be retrieved using the RetrieveApplicationRibbonRequest as shown in the following sample.
//Retrieve the Appliation Ribbon
RetrieveApplicationRibbonRequest appribReq = new RetrieveApplicationRibbonRequest();
RetrieveApplicationRibbonResponse appribResp = (RetrieveApplicationRibbonResponse)_serviceProxy.Execute(appribReq);
System.String applicationRibbonPath = Path.GetFullPath(exportFolder + "\\applicationRibbon.xml");
File.WriteAllBytes(applicationRibbonPath, unzipRibbon(appribResp.CompressedApplicationRibbonXml));
'Retrieve the Appliation Ribbon
Dim appribReq As New RetrieveApplicationRibbonRequest()
Dim appribResp As RetrieveApplicationRibbonResponse = CType(_serviceProxy.Execute(appribReq), RetrieveApplicationRibbonResponse)
Dim applicationRibbonPath As String = Path.GetFullPath(exportFolder & "\applicationRibbon.xml")
File.WriteAllBytes(applicationRibbonPath, unzipRibbon(appribResp.CompressedApplicationRibbonXml))
Retrieve entity ribbons
To retrieve the ribbon definition for entities, you can just include the name of the entity as a parameter to the RetrieveEntityRibbonRequest.
To retrieve the ribbon definitions for all entities that support the ribbon you need a list of those system entities that have ribbon definitions that vary from the entity ribbon template. The following sample shows an array of all the system entities that have ribbon definitions.
//This array contains all of the system entities that use the ribbon.
public System.String[] entitiesWithRibbons = {"account",
"activitymimeattachment",
"activitypointer",
"appointment",
"bulkoperation",
"calendar",
"campaign",
"campaignactivity",
"campaignresponse",
"competitor",
"connection",
"contact",
"contract",
"contractdetail",
"convertrule",
"convertruleitem",
"customeraddress",
"discount",
"discounttype",
"email",
"emailserverprofile",
"entitlement",
"entitlementchannel",
"entitlementtemplate",
"entitlementtemplatechannel",
"fax",
"goal",
"goalrollupquery",
"importfile",
"incident",
"invoice",
"invoicedetail",
"kbarticle",
"kbarticlecomment",
"lead",
"letter",
"list",
"listmember",
"mailbox",
"metric",
"opportunity",
"opportunityproduct",
"partnerapplication",
"phonecall",
"postfollow",
"pricelevel",
"product",
"productpricelevel",
"queue",
"queueitem",
"quote",
"quotedetail",
"recurringappointmentmaster",
"report",
"rollupfield",
"routingrule",
"routingruleitem",
"salesliterature",
"salesliteratureitem",
"salesorder",
"salesorderdetail",
"service",
"serviceappointment",
"sharepointdocument",
"sharepointdocumentlocation",
"sharepointsite",
"site",
"sla",
"slaitem",
"socialactivity",
"socialprofile",
"systemuser",
"task",
"team",
"teamtemplate",
"territory",
"uom",
"uomschedule",
"userquery"};
'This array contains all of the system entities that use the ribbon.
Public entitiesWithRibbons() As String = {"account", "activitymimeattachment", "activitypointer", "appointment", "bulkoperation", _
"campaign", "campaignactivity", "campaignresponse", "competitor", "connection", "contact", _
"contract", "contractdetail", "customeraddress", "discount", "discounttype", "email", "fax", "goal", _
"importfile", "incident", "invoice", "invoicedetail", "kbarticle", "kbarticlecomment", "lead", _
"letter", "list", "listmember", "metric", "opportunity", "opportunityproduct", "phonecall", _
"pricelevel", "product", "productpricelevel", "queueitem", "quote", "quotedetail", _
"recurringappointmentmaster", "report", "salesliterature", "salesorder", "salesorderdetail", _
"service", "serviceappointment", "sharepointdocumentlocation", "sharepointsite", "systemuser", _
"task", "team", "territory", "uom", "uomschedule", "userquery"}
The following sample shows how to retrieve the ribbon definitions for a set of entities.
//Retrieve system Entity Ribbons
RetrieveEntityRibbonRequest entRibReq = new RetrieveEntityRibbonRequest() { RibbonLocationFilter = RibbonLocationFilters.All };
foreach (System.String entityName in entitiesWithRibbons)
{
entRibReq.EntityName = entityName;
RetrieveEntityRibbonResponse entRibResp = (RetrieveEntityRibbonResponse)_serviceProxy.Execute(entRibReq);
System.String entityRibbonPath = Path.GetFullPath(exportFolder + "\\" + entityName + "Ribbon.xml");
File.WriteAllBytes(entityRibbonPath, unzipRibbon(entRibResp.CompressedEntityXml));
//Write the path where the file has been saved.
Console.WriteLine(entityRibbonPath);
}
'Retrieve system Entity Ribbons
Dim entRibReq As New RetrieveEntityRibbonRequest() With {.RibbonLocationFilter = RibbonLocationFilters.All}
For Each entityName As String In entitiesWithRibbons
entRibReq.EntityName = entityName
Dim entRibResp As RetrieveEntityRibbonResponse = CType(_serviceProxy.Execute(entRibReq), RetrieveEntityRibbonResponse)
Dim entityRibbonPath As String = Path.GetFullPath(exportFolder & "\" & entityName & "Ribbon.xml")
File.WriteAllBytes(entityRibbonPath, unzipRibbon(entRibResp.CompressedEntityXml))
'Write the path where the file has been saved.
Console.WriteLine(entityRibbonPath)
Next entityName
Any custom entities also support ribbon customizations. To get a list of custom entities, use the RetrieveAllEntitiesRequest and retrieve the names of custom entities. The following sample shows how to retrieve ribbon definitions for all custom entities.
//Check for custom entities
RetrieveAllEntitiesRequest raer = new RetrieveAllEntitiesRequest() { EntityFilters = EntityFilters.Entity };
RetrieveAllEntitiesResponse resp = (RetrieveAllEntitiesResponse)_serviceProxy.Execute(raer);
foreach (EntityMetadata em in resp.EntityMetadata)
{
if (em.IsCustomEntity == true && em.IsIntersect == false)
{
entRibReq.EntityName = em.LogicalName;
RetrieveEntityRibbonResponse entRibResp = (RetrieveEntityRibbonResponse)_serviceProxy.Execute(entRibReq);
System.String entityRibbonPath = Path.GetFullPath(exportFolder + "\\" + em.LogicalName + "Ribbon.xml");
File.WriteAllBytes(entityRibbonPath, unzipRibbon(entRibResp.CompressedEntityXml));
//Write the path where the file has been saved.
Console.WriteLine(entityRibbonPath);
}
}
}
'Check for custom entities
Dim raer As New RetrieveAllEntitiesRequest() With {.EntityFilters = EntityFilters.Entity}
Dim resp As RetrieveAllEntitiesResponse = CType(_serviceProxy.Execute(raer), RetrieveAllEntitiesResponse)
For Each em As EntityMetadata In resp.EntityMetadata
If em.IsCustomEntity = True AndAlso em.IsIntersect = False Then
entRibReq.EntityName = em.LogicalName
Dim entRibResp As RetrieveEntityRibbonResponse = CType(_serviceProxy.Execute(entRibReq), RetrieveEntityRibbonResponse)
Dim entityRibbonPath As String = Path.GetFullPath(exportFolder & "\" & em.LogicalName & "Ribbon.xml")
File.WriteAllBytes(entityRibbonPath, unzipRibbon(entRibResp.CompressedEntityXml))
'Write the path where the file has been saved.
Console.WriteLine(entityRibbonPath)
End If
Next em
End Using
See Also
Customize commands and the ribbon
Command bar or ribbon presentation
Export, prepare to edit, and import the ribbon
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright