Open XML Developer Workshop Working with the Packaging API

Open XML Developer Workshop

Working with the Packaging APIWorking with the Packaging API


DisclaimerDisclaimerThe information contained in this slide deck represents the current view of Microsoft Corporation on the issues discussed as of the date of

publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This slide deck is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this slide deck may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this slide deck. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this slide deck does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred. <INCLUDE THIS DISCLAIMER ONLY WHEN APPLICABLE TO YOUR CONTENT >

© (Year of Publication) Microsoft Corporation. All rights reserved.Microsoft, <plus, in alphabetical order, all Microsoft trademark used in your slide deck> are either registered trademarks or trademarks of

Microsoft Corporation in the United States and/or other countries.The names of actual companies and products mentioned herein may be the trademarks of their respective owners.< If your slide deck does not contain any fictitious names, etc. this entire paragraph can be removed from the disclaimer .>< insert the appropriate year the slide deck was created. My guess will be 2005 and 2006 (when we get there).Prior to sending me the slide deck , please scrub your document against the Microsoft TM list for all Msft TM’s used in your document and

list them in alphabetical order in the proper manner as described in the MSFT TM bugging list/document.>


OverviewOverview

Introduction to the Open Packaging Convention Working with System.IO.Packaging


Lesson: Introduction to the Open Packaging ConventionLesson: Introduction to the Open Packaging Convention

Open XML Formats ArchitectureComponents of the Open Packaging ConventionKey Scenarios


Open XML Formats ArchitectureOpen XML Formats Architecture

File Container

Document Properties

Comments

WordML / Spreadsheet ML

Custom XML

Embedded Code

Images / Video / Sound

User view: single Office file

Document PartsMost parts are XMLEach XML part is a discrete componentCan add, extract and modify individual parts without using Office programsCorruption of any part would not prohibit the file from opening

Developer view: modular file


Elements of the Open Packaging ConventionElements of the Open Packaging Convention

Package – The containerDocument Parts – The files inside the containerRelationships – Every part that references other parts does so via a relationship

Document Properties

Application Properties

Custom PropertiesSheet 1

Sheet 2

Sheet 3Strings

Theme

Workbook


Elements of the Open Packaging ConventionThe packageElements of the Open Packaging ConventionThe package

A package isA logical entity that holds a collection of partsAn aggregation of all pieces of a document in a single objectNot tied to a physical representation

ZIP, Database, loose files

Special featuresCore propertiesThumbnail partsDigital signatures



Some of the core properties:CategoryContentTypeCreatorDescriptionIdentifierKeywordsModifiedRevisionLastModifiedBySubjectTitleVersion



Digital Signatures in the PackageAllows the validation of package integrity using X.509 certificatesYou can sign

All parts, including digital signaturesAll relationships, or a subset of a set of relationships

Navigate signatures with the Digital Signature Origin Part



Digital Signature

Origin Part

Digital Signature XML Signature

Part

Digital Signature XML Signature

Part

Signed Part

Signed Part

Signed Part

Signed Part

Relationship Relationship

URI

URIURI

URI

X.509 Certificate

Part

X.509


Elements of the Open Packaging ConventionDocument partsElements of the Open Packaging ConventionDocument parts

A part isanalogous to a file on the file systemstored inside the package in a specific location reachable via a URIstored with a specific content typemainly XML but other native types as well

Images, sounds, video, OLE objects

A part can use growth hints to allow uninterrupted content growth


Elements of the Open Packaging ConventionDocument partsElements of the Open Packaging ConventionDocument parts

• Content types define the type of media stored in the part. It is defined by:

A media type, sub type, 19 optional parameters

The content types partdefines mappings from part to content typeis not directly addressable

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><Types> <Default Extension="jpeg" ContentType="image/jpeg" /> <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" /> <Default Extension="xml" ContentType="application/xml" /> <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>


Elements of the Open Packaging ConventionRelationship partsElements of the Open Packaging ConventionRelationship parts

A relationshipTies elements inside the package to each otherAllows you to step through the document without parsing parts


Elements of the Open Packaging ConventionRelationship partsElements of the Open Packaging ConventionRelationship parts

A relationship has its own relationship typeA way to say ‘hey that file with XML content is the styles part’It gives meaning to the content in a part for a given context

Document.XML…wordprocessingml.document.main+xml

Styles.xml…wordprocessingml.styles+xml

http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles


Document Assembly ScenariosDocument Assembly Scenarios

Useful when documents need to be generated from structured data:

Create documents for users from form dataCreate pitchbooks from slide librariesPull data out of SQL or LOBi servers and publish in OpenXML

Recommendation: Start from a template


Document Inspection and Redaction ScenariosDocument Inspection and Redaction Scenarios

SecurityRemove active content (VBA, controls)

PrivacyRemove comments, revisions, hidden text before publicationRemove or alter document propertiesInsert headers/footers and watermarks


Document Merge ScenariosDocument Merge Scenarios

Aggregate data from several documents into oneMerge two independent copies into one


Document Lifecycle and Workflow ScenariosDocument Lifecycle and Workflow Scenarios

Rules applicationApply styles, fonts, chart types

Transcoding of documentsTranscode parts of documents into text other XML or HTML, for example.

Crossover with Validation scenarios


Document Validation and Debugging ScenariosDocument Validation and Debugging Scenarios

Validate structure of partsValidate XML against schema and for well-formednessValidate document by type or class

Cross-over with Workflow


OverviewOverview

Introduction to the Open Packaging ConventionWorking with System.IO.Packaging


Lesson: Working with System.IO.PackagingLesson: Working with System.IO.Packaging

Components of System.IO.PackagingTraversing a PackageManipulating a PackageOpen XML Password Hashing


Components of System.IO.Packaging The libraryComponents of System.IO.Packaging The library

Part of Windows Presentation FoundationPart of Windows Presentation FoundationInstalled with .NET 3.0Installed with .NET 3.0Requires .NET 2.0 RuntimeRequires .NET 2.0 RuntimeEnables package manipulation forEnables package manipulation for

Office Open XML File FormatsOffice Open XML File FormatsXML Paper Specification FilesXML Paper Specification FilesAny Open Packaging Convention filesAny Open Packaging Convention files


Components of System.IO.Packaging The PackageComponents of System.IO.Packaging The Package

Package class provides Package class provides methods to create, methods to create, enumerate and delete enumerate and delete the following entitiesthe following entities

PackagePackagePackage PropertiesPackage PropertiesPackageRelationshipsPackageRelationshipsPackagePartsPackageParts

Common Package Parts

Pack

age

Rela

tions

hips

Pack

age

Rela

tions

hips

Core PropertiesCore Properties

Digital SignaturesDigital Signatures

Specific Format Parts

Office DocumentOffice Document

Part

Rel

ation

ship

sPa

rt R

elati

onsh

ips XML PartXML Part

XML PartXML Part

Part

Rel

sPa

rt R

els

Etc…


Components of System.IO.Packaging The PackageRelationshipComponents of System.IO.Packaging The PackageRelationship

Required to find parts (part Required to find parts (part names are not guaranteed)names are not guaranteed)Iterate through a Iterate through a RelationshipCollection by RelationshipCollection by type or IDtype or IDRelationship PropertiesRelationship Properties

IDIDPackagePackageRelationshipTypeRelationshipTypeSourceUriSourceUriTargetModeTargetModeTargetUriTargetUri


Pack

age

Rela

tions

hips

Pack

age

Rela

tions

hips





Part

Rel

ation

ship

sPa

rt R

elati

onsh


XML PartXML Part

Part

Rel

sPa

rt R

els

Etc…


Components of System.IO.Packaging The PackagePartComponents of System.IO.Packaging The PackagePart

A PackagePart is the object A PackagePart is the object of data within the Packageof data within the PackageIt provides support to It provides support to create, enumerate and create, enumerate and delete part relationshipsdelete part relationshipsGet data as a Get data as a System.IO.StreamSystem.IO.StreamPackagePart properties:PackagePart properties:

CompressionOptionCompressionOptionContentTypeContentTypePackagePackageUriUri


Pack

age

Rela

tions

hips

Pack

age

Rela

tions

hips





Part

Rel

ation

ship

sPa

rt R

elati

onsh


XML PartXML Part

Part

Rel

sPa

rt R

els

Etc…


Components of System.IO.Packaging The PackUriHelper Components of System.IO.Packaging The PackUriHelper

Find a related PackagePart by searching relationships, Find a related PackagePart by searching relationships, either by relationship type or relationship IDeither by relationship type or relationship ID

This returns a list of PackageRelationship objectsThis returns a list of PackageRelationship objects

A PackageRelationship defines two relative URIsA PackageRelationship defines two relative URIsSource URI, pointing to the source PackagePartSource URI, pointing to the source PackagePartTarget URI, pointing to the target PackagePartTarget URI, pointing to the target PackagePart

Retrieve a PackagePart by using a URI relative to the root Retrieve a PackagePart by using a URI relative to the root of the Packageof the Package

Translation of Source and Target URIs is requiredTranslation of Source and Target URIs is requiredUse the PackUriHelper class to aid in the translationUse the PackUriHelper class to aid in the translation


<Relationships xmlns=“http://schemas.openxmlformats.org/package/2006/relationships”> <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/ relationships/metadata/core-properties" Target="docProps/core.xml" /> <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/ officeDocument/2006/relationships/officeDocument" Target="word/document.xml" /> </Relationships>

<w:document xmlns:w="http://schemas.openxmlformats.org/ wordprocessingml/2006/main"> <w:body> <w:p> <w:r> <w:t>Hello World!</w:t> </w:r> </w:p> </w:body></w:document>

Traversing a PackageOpening the “Start-Part”Traversing a PackageOpening the “Start-Part”


Traversing a PackageOpening the “Start-Part”Traversing a PackageOpening the “Start-Part”

Now using the Packaging APIstring relationshipType = "http://schemas.openxmlformats.org/...";

using (Package package = Package.Open("mydocument.docx")){ PackageRelationship relationship = null; foreach (PackageRelationship searchRelation in package.GetRelationshipsByType(relationshipType)) { relationship = searchRelation; break; } Uri partUri = PackUriHelper.ResolvePartUri( relationship.SourceUri, relationship.TargetUri); PackagePart mainPart = package.GetPart(partUri); // Do something with mainPart}


<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"> <Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/ relationships/theme" Target="theme/theme1.xml" /> </Relationships>

<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme"> <a:themeElements> <a:clrScheme name="Office"> <a:dk1> <a:sysClr val="windowText" lastClr="000000" /> </a:dk1>

Traversing a PackageOpening a related document partTraversing a PackageOpening a related document part


Traversing a PackageOpening a related document partTraversing a PackageOpening a related document part

You can retrieve a Part using a relationshipID

Or using the relationshipType

string relID= “rId1”;PackageRelationship imagerelationship = mainPart.GetRelationship(relID);Uri imagePartUri = PackUriHelper.ResolvePartUri( imagerelationship.SourceUri, imagerelationship.TargetUri);PackagePart imagepart = mainPart.Package.GetPart(imagePartUri);

string RT_Image = “http://schemas....”;int imageCount = 0;foreach (PackageRelationship relation in mainPart.GetRelationshipsByType(RT_Image)){ imageCount++;}Console.WriteLine("The part references {0} unique images", imageCount);


Traversing a PackageTraversing a Package


Manipulating a PackageCreating New PackagesManipulating a PackageCreating New Packages

The Packaging API allows you to create new Packages based on a file or stream Package.Open creates the Package when using the correct parameters

using (Package package = Package.Open("newFile.xlsx", FileMode.OpenOrCreate, FileAccess.ReadWrite)){ // the Package is now on disk, 0 bytes in size}


Manipulating a PackageAdding partsManipulating a PackageAdding parts

Create a PackagePart usingLocation (Uri)Content type (String)

You can not alter the content type later onMake sure the location is not in useUse a Stream to modify the PackagePart contents

string contentType = “application/xml”;PackagePart part = package.CreatePart( new Uri(targetPath, UriKind.Relative), contentType);using (StreamWriter writer = new StreamWriter( part.GetStream(FileMode.Create, FileAccess.Write))){ using (StreamReader reader = new StreamReader(path)) { writer.Write(reader.ReadToEnd()); }}


Manipulating a PackageRelating the partsManipulating a PackageRelating the parts

Each PackagePart needs to be related to its child partsRelationship IDRelationshipTypeTargetMode

using (Package package = Package.Open("newFile.xlsx", FileMode.OpenOrCreate, FileAccess.ReadWrite)){ PackagePart workbook = AddToPackage("SampleSheet/workbook.xml", "/workbook.xml", CT_Workbook, package); PackagePart sheet = AddToPackage("SampleSheet/sheet1.xml", "/sheet1.xml", CT_Sheet, package); package.CreateRelationship( new Uri("/workbook.xml", UriKind.Relative), TargetMode.Internal, RT_MainDocument, "rId1"); workbook.CreateRelationship( new Uri("/sheet1.xml", UriKind.Relative), TargetMode.Internal, RT_Sheet, "rId1");}


ResourcesResources

OpenXMLDeveloper.orgKevin Boske’s Blog

http://blogs.msdn.com/kevinboskeBrian’s Blog

http://blogs.msdn.com/brian_jonesWinFX Developer Center

http://msdn.microsoft.com/winfx/XPS Blog:

http://blogs.msdn.com/xps



Open XML Password HashingOpen XML Password HashingPassword: test

Characters: 4 Initial Hash: 0

Hashed value: CBEB

Documents

Open XML Developer Workshop Working with the Packaging API