PDSAHaystackCh10-XML-DataClasses

Chapter 10

XML Data Classes TableofContents

Chapter 10 ................................................................................................................... 10-1

XML Data Classes ....................................................................................................... 10-1

XML Data Classes ........................................................................................... 10-1

Product.xml ...................................................................................................... 10-2

Methods in Generated XML Data Classes ....................................................... 10-2

BuildCollection Method .................................................................................... 10-3The Code for BuildCollection ................................................................ 10-4

Samples ........................................................................................................... 10-6

Generating XML Data Classes ......................................................................... 10-8

Chapter Index ................................................................................................. 10-13

XML Data Classes If you deal with XML files a lot, you will like the ability to create data classes that will wrap up the selecting, inserting, editing and the deleting of elements. Haystack will read in XML files that model a single relation and allow you to create a class wrapper to select and modify nodes in the xml. The XML file can be element, attribute or a combination of the two as long as the XML only contains a single row in a single table. For examples see the .XML files in the [HaystackInstallFolder]\Samples folder. All of the samples in this chapter come from the solution contained in the [InstallFolder]\Haystack\Samples\xx\Xml_Sample_xx folders.

XML Data Classes

10-2 Haystack Code Generator for .NET Copyright 2010-2011 by PDSA, Inc.

All rights reserved. Reproduction is strictly prohibited.

Product.xml For all of the samples in this chapter, a Product.xml file will be used. A fragment of this file is shown in Listing 1.

1 PDSA .NET Productivity Framework 3/3/2002 12:00:00 AM 20000 False 200 2 Architecting ASP.NET Applications 2002-04-03T00:00:00-07:00 10 19.95 false

Listing 1: Product.xml file

Methods in Generated XML Data Classes Given the Product.xml file listed above you can generate a class from Haystack that will give you several methods as shown in Table 1 below.

Method Description

BuildCollection This method will return a collection class of objects created from your XML file. All nodes in your XML file are returned. You could use this method as a template and add on additional methods that apply a WHERE clause using LINQ to XML.

CheckBusinessRule This method will check the business rule(s) for any specific property/xml element. A status enumeration of passed or failed is returned.

CheckBusinessRules This method will check all business rules on all properties/xml elements. A status enumeration of passed or failed is returned.

CloneEntity This method will clone one complete xml element to a new object.

Delete Deletes a single xml element from your xml file.

BuildCollection Method

Haystack Code Generator for .NET 10-3 Copyright 2010-2011 by PDSA, Inc. All rights reserved. Reproduction is strictly prohibited.

DoesUniqueKeyExist This method will check to see if a specific unique key element exists in the XML file. NOTE: This assumes you have identified one of your elements as a unique key element. If your xml file does not have a unique key element, then this method will not work.

Insert Inserts a new xml element into your xml file.

GetNextUniqueKeyValue If you have identified one of your elements as a unique key and that is of an integer data type, then you can call this method and it will find the maximum value in the existing file and automatically increment that to the next number.

GetXElements Returns all elements in your XML file as a collection of .NET XElement objects.

LoadByUniqueKey Loads a single element into an entity object based on a single value you have identified as a unique key.

Update Updates a single element in your xml file.

Validate Performs a validation on all the business rules for each element/property. This method will throw a PDSAValidationException object if any business rules fail. This method is called by the Insert and Update methods prior to modifying the file.

Table 1: Methods of the XML Data Classes

BuildCollection Method As a part of the Manager class, there is a BuildCollection method that returns all elements from your XML file. This method will build a collection of Product objects that can be bound to any typical data-bound object. Below is a sample of how to call this method.

XML Data Classes



C# private void BuildCollectionSample() { ProductXmlManager mgr = null; ProductXmlCollection coll; try { mgr = new ProductXmlManager(AppConfig.ProductXmlFileName); // Build collection of XML coll = mgr.BuildCollection(); // Display the Data lstData.DataContext = coll; } catch (Exception ex) { MessageBox.Show(ex.ToString()); } } VB.NET Private Sub BuildCollectionSample() Dim mgr As New ProductXmlManager(AppConfig.ProductXmlFileName) Dim coll As ProductXmlCollection Try ' Build collection of XML coll = mgr.BuildCollection() ' Display the Data lstData.DataContext = coll Catch ex As Exception MessageBox.Show(ex.ToString()) End Try End Sub

The Code for BuildCollection If you wish to restrict the amount of data coming back from your XML file, you could always modify the BuildCollection method, or copy this method to your own method in the Manager class and apply any WHERE or ORDER BY statements to the LINQ to XML code. Below is what the BuildCollection method looks like.

BuildCollection Method


C# public ProductXmlCollection BuildCollection() { XElement xElem; xElem = DataObject.GetXElements(); try { var elems = from cs in xElem.Elements(DataObject.TopElementName) select cs; ProductXmlCollection coll = new ProductXmlCollection(); foreach (XElement item in elems) { ProductXml entity = new ProductXml(); DataObject.XElementToEntity(item, entity); coll.Add(entity); } return coll; } catch (Exception ex) { throw new PDSAXmlDataClassException( "Error trying read from XML file: " + FileName, ex, ClassName, "GetProductXmls", FileName); } } VB.NET Public Function BuildCollection() As ProductXmlCollection Dim xElem As XElement Dim coll As New ProductXmlCollection() Dim entity As ProductXml xElem = DataObject.GetXElements() Try Dim elems = From cs In _ xElem.Elements(DataObject.TopElementName) _ Select cs For Each item As XElement In elems entity = New ProductXml() DataObject.XElementToEntity(item, entity) coll.Add(entity) Next Return coll Catch ex As Exception Throw New PDSAXmlDataClassException( _

XML Data Classes



"Error trying read from XML file: " + FileName, _ ex, ClassName, "GetProductXmls", FileName) End Try End Function

As you can see in the above code, the DataObject is used to open the XML file and return a .NET XElement object. Once you have this XElement object you can iterate over the nodes using LINQ to XML. Each time through a node you create a new ProductXml instance and move the xml elements into the properties of the ProductXml entity class. The DataObject.XElementToEntity method is responsible for moving the data from the XML element to the entity object.

Samples There are samples of all of the methods listed in Table 1 in the sample application located under the [InstallFolder]\Haystack\Samples\xx\Xml_Sample_xx folder. A screen shot of the sample is shown in Figure 1 and Figure 2. You should open up this sample and take a look at all the things you can do with XML files using Haystack.

Samples


Figure 1: The XML Data Classes Sample

XML Data Classes



Figure 2: The XML Data Classes Sample

Generating XML Data Classes To generate a data class from an XML file you click on the Haystack menu, then choose the XML Class Generation menu (Figure 3). This will bring up the Haystack XML Code Generator for .NET as shown in Figure 4.

Generating XML Data Classes


Figure 3: Click on XML Class Generation to launch the XML Code Generator

Figure 4: XML Code Generator (XML Gen Info Tab)

On the XML Gen Info Tab is where you will setup how you want the code generated.

Field Description

Namespace This is the name of this project that will be presented in the Combo box drop down on the main Haystack screen. Each project must have a unique name in Haystack.

XML Class Suffix A description of this project.

Private Variable (field) Prefix

Any prefix you wish to put on fields that are generated in classes.

Make all Elements/Attributes Required

Check this if you want all elements in your XML file to be required. Setting this will create a business rule automatically for each element to ensure that it is filled in.

Generate Integer If your XML file uses an integer data type for a unique identifier on each

XML Data Classes



Unique Key On Insert?

row in your XML element you can check this and the XML Data Class engine will automatically create a unique integer key for you when you perform an Insert. Kind of like an auto-number in a database engine.

Generation Language

The .NET language which you wish to use to generate for this XML Data Class.

Figure 5: XML Code Generator (XML File Tab)

On the XML File Tab you will fill in the path and file name of the XML file you wish to generate a data class. If your file is mostly (or all) element based XML. This will help the XML code generator set a flag on each column identifying it as an element or an attribute. Click on the Read XML File button when you have filled in the name of the XML file. The columns and the data from the XML file will then be read in and displayed in the grid. Put in the name of the class you want to generate and then click on the Set Data Types on Columns button. This will display the XML Column Information screen (Figure 6).

Field Description

Select an XML File Fill in the full path and file name of the XML file you wish to generate a data class for.

XML is Mostly Element Based?

Check this box if the XML file you are reading in is mostly element-based XML. Leave this unchecked if the XML file you are reading in is mostly attribute based. If it is a mixture of both, then just leave it unchecked. You will have an opportunity to set Element or Attribute in the XML Column Information screen.

Read XML File Button

Click on this button to read your XML file.



Class Name Set the Class Name to generate for this XML file.

ORDER BY Element Select any of your elements to order the XML data in.

Set Data Types on Columns Button

Click here to set the data types for each column and whether each column is an element or an attribute.

Figure 6: XML Column Information Screen

On the XML Column Information screen is where you will click on each column and set information about that column. For example, on this screen you will set the data type for each column and the private and public property names to generate. You should also set one of your columns as the Unique Key.

Field Description

Private Name The backing field name for the public property.

XML Data Classes



Public Name The public property name.

Header Text The text to use when creating labels for detail forms, or for grid column headers.

Default Value A default value to set the public property to when creating a new instance of the entity class for this XML file.

.NET Type The .NET data type you wish to use to hold the data in this column.

Minimum Value Set this when your column is a numeric data type and you wish to enforce a business rule that the value must be greater than or equal to this value.

Maximum Value Set this when your column is a numeric data type and you wish to enforce a business rule that the value must be less than or equal to this value.

Minimum Length Set this when your column is a string data type and you wish to enforce a business rule that the length of the string must be greater than or equal to this value.

Is Element? Set this to true if this column is an element in the XML file. Set to false if this column is an attribute in the XML file.

Is Description Field?

Set this to true if you want this column to be the description field.

Is Unique Key? Set this to true if this column is the unique key field for a row of data in the XML file.

Is Required? Set this to true if the user will be required to fill in this value.

Required Message Set this to a message to display to the user if they do not fill in this column of data.

Save Button Click this button save any changes you made to this column.

Close Button Click this to close this form and return back to the XML generation screen.

When you are done setting the information for each column and identifying each as an element or an attribute, you can then click on the Generate button and the data classes and validation classes will be generated. In addition a WPF User Control will also be generated for adding, editing and deleting data using the generated XML data classes.



Summary The ability to generate XML data classes will simplify your use of XML files. In addition it will provide a standard approach to working with your XML files. You can add your own methods by putting them into the Manager class. The Entity class is a partial class, so you can add your own additional properties into the Entity class that you will not regenerate.

Chapter Index

..NET Type for XML Data Classes, 10-12

BBuildCollection, 10-2 BuildCollection Method, 10-3

CCheckBusinessRule Method, 10-2 CheckBusinessRules Method, 10-2 Class Name for XML Data Classes, 10-11 CloneEntity Method, 10-2 Close Button for XML Data Classes, 10-12

DDefault Value for XML Data Classes, 10-12 Delete Method, 10-2 DoesUniqueKeyExist Method, 10-3

GGenerate Integer Unique Key on Insert for

XML Data Classes, 10-10 Generating XML Data Classes, 10-8 Generation Language for XML Data

Classes, 10-10 GetNextUniqueKeyValue Method, 10-3 GetXElements Method, 10-3

HHeader Text for XML Data Classes, 10-12

IInsert Method, 10-3 Is Description Field? for XML Data Classes,

10-12 Is Element? for XML Data Classes, 10-12 Is Required? for XML Data Classes, 10-12 Is Unique Key? for XML Data Classes, 10-12

LLoadByUniqueKey Method, 10-3

MMake all Elements Required for XML Data

Classes, 10-9 Maximum Value for XML Data Classes, 10-

12 Methods in Generated XML Data Classes,

10-2 Minimum Length for XML Data Classes, 10-

12 Minimum Value for XML Data Classes, 10-12

NNamespace for XML Data Classes, 10-9

XML Data Classes



OORDER BY Element for XML Data Classes,

10-11

PPrivate Name for XML Data Classes, 10-11 Private Variable (field) Prefix for XML Data

Classes, 10-9 Product.xml file, 10-2 Public Name for XML Data Classes, 10-12

RRead XML File Button for XML Data

Classes, 10-10 Required Message for XML Data Classes,

10-12

SSave Button for XML Data Classes, 10-12 Select an XML File for XML Data Classes,

10-10 Set Data Types on Columns Button for XML

Data Classes, 10-11

UUpdate Method, 10-3

VValidate Method, 10-3

XXML Class Suffix, 10-9 XML Data Classes, 10-1

BuildCollection Method, 10-2, 10-3, 10-4 CheckBusinessRule Method, 10-2 CheckBusinessRules Method, 10-2 CloneEntity Method, 10-2 Delete Method, 10-2 DoesUniqueKeyExist Method, 10-3 Generating, 10-8 GetNextUniqueKeyValue Method, 10-3 GetXElements Method, 10-3 Insert Method, 10-3 LoadByUniqueKey Method, 10-3 Update Method, 10-3 Validate Method, 10-3

XML Data Classes Samples, 10-6 XML is Mostly Element Based? for XML

Data Classes, 10-10

Documents

PDSAHaystackCh10-XML-DataClasses