We're sorry Aspose doesn't work properply without JavaScript enabled.

Free Support Forum - aspose.com

How to represent OOXML versions in the Aspose.Words API?

As of today we have three OOXML versions/flavours:

  • OOXML ECMA-376 1st Edition, 2006 (this is Word 2007) - as of today, Aspose.Words supports only this.
  • ISO/IEC 29500:2008 Transitional (Word 2010) - we have code ready for the upcoming release that will support this.
  • ISO/IEC 29500:2008 Strict - Aspose.Words will support this some time in the future.

The question I have to all of the customers of Aspose.Words is:

What is the best way to represent the different OOXML versions in the Aspose.Words API?

The general requirements I have:

  1. It should be easy to use and look natural and consistent.
  2. It should follow the accepted .NET framework coding guidelines.

The two scenarios we are currently considering are:

  • Add the OoxmlCompliance enum and add the SaveOptions.OoxmlCompliance property.
  • Add new values to the SaveFormat enum.

I will quickly discuss both of the scenarios below and I am looking for your feedback and new ideas as well.

Scenario 1: Add the OoxmlCompliance enum and a new option to SaveOptions

Saving a document in the new ISO 29500 format will look like this:

// You need to set the option. The default will be ECMA-376 to preserve existing behaviour.
doc.SaveOptions.OoxmlCompliance = OoxmlCompliance.Iso29500_2008_Transitional;
/// Allows to specify which OOXML specification will be used for the output DOCX file.
public enum OoxmlCompliance
/// ECMA-376 1st Edition, 2006.

/// ISO/IEC 29500:2008 Transitional compliance level.

ISO/IEC 29500:2008 specification is sometimes referred to as as ECMA-376 2nd Edition.


What I don't like:

  1. It requires an extra line of code to select the OOXML version/flavour.
  2. The names of the enum values are quite ugly and don't follow .NET guidelines, but I want the names to be informative. Tried other variants and did not like them.

Scenario 2: Add more values to the SaveFormat enum.

Saving a document in OOXML could look like this:

// This is for the new format.
doc.Save(@"C:\MyFile.docx", SaveFormat.Docx_Iso29500_2008_Transitional);

// This is for the existing ECMA-376 format to keep the behavior unchanged.
doc.Save(@"C:\MyFile.docx", SaveFormat.Docx);
// This is to maintain consistency (have all versions named explicitly)
doc.Save(@"C:\MyFile.docx", SaveFormat.Docx_Ecma376_2006);

What I don't like:

We have SaveFormat.Docx, SaveFormat.Docm, we probably should have SaveFormat.Dotx and SaveFormat.Dotm and if we want to add ISO29500 Transitional and Strict and also explicit name for ECMA-376 we could end up with 4 x 4 = 16 enum values like SaveFormat.Docm_Iso29500_2008_Transitional, SaveFormat.Docx_Iso29500_2008_Transitional etc. Too noisy.

Any ideas?

A very difficult choice, merits and pitfalls with either, here are my thoughts:

Personally I feel option 1 is probably the best bet as although there are differences between the formats, they are all arguably ooXml, so having the different “SaveFormat” enum values doesn’t seem to make sense. It also seems similar to the way Html and Text are saved with the options affecting the outcome but not technically it’s underlying format.

I’m also worried that “SaveFormat” would start to bloat as more and more “versions” of ooXml get added, we have a new “verson” after 3 years so whats to say we won’t have another in 3 years time?

I would strongly suggest option 2 - given your stated requirement of being easy to use and remaining consistent with the rest of Aspose.Words.

I think you need to think about usage scenarios with those who use Aspose.Words. I am currently evaluating and we have some code which does a DB look up to determine the save format. At the moment in our tests we can easy map that output to a single parameter in the Save method. It is done in a single line as we store the SaveFormat enum in our DB.

If you went for Option 1 then we would have to amend our code with an ugly “IF” block to do an extra step for 2010 DOCX files and perhaps even add another DB column to maintain this extra data. If you then followed the approach for other “compliance” types; say a future version of XPS or Epub we are looking at another code change (as it would need to be another SaveOptions property) and potentially another database column.

Option 2 would mean no change for us we would just add the new Enum value to our database.

I would also say typically in the .NET Framework (thought I haven’t checked!) I would expect to be able to influence all aspects of a Save operation in the method it’self rather than having to set a property before I invoke the method.

Hope this helps - and good luck with the next release!

Thanks for your comments so far, all have merits.

It is obvious that each document format should have its own SaveFormat value. The question comes down to whether such “flavours” or “versions” should be better treated as different formats or as a single format with options.

There is also the SaveFormat.FlatOpc enum value that currently saves in the ECMA-376 standard. If we decide to add enum values to SaveFormat for ISO29500 then SaveFormat.FlatOpc will also have to be multiplied. Next, OpenDocument ODT will soon have 1.2 standartized and we will offer saving as 1.1 or 1.2. This will require adding more enum values. I think we risk creating a mess of the enum.

So I am inclining towards adding save options. It will still be easy one line of code to save in the most likely scenario, but if you want more control you have to add a few more lines of code. That is along with .NET design gudelines.

@turnblue - maybe you need another column in the database that stores a little XML data that can be used to populate the SaveOptions object. Maybe we can add the ability to load/save such XML configuration to the SaveOptions object. This will solve you problem of configuring the save format/version/options without changing the code.

I would go with Scenario 1, especially since this list will probably grow in the future.

Yes romank - your idea of going with an XML config is a great idea, especially if you are going to extend the save options in future as it could avoid people having to change code (certainly in the case where we are looking at using your library).