Transcript Lesson: Introduction to the Open Packaging Convention

Open XML Packages,
Parts and Relationships
Open XML Developer Workshop
Disclaimer
The 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.
© 2006 Microsoft Corporation. All rights reserved.
Microsoft, 2007 Microsoft Office System, .NET Framework 3.0, Visual Studio, and Windows Vista 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.
Open XML Developer Workshop
Overview
Introduction to the Open Packaging Convention
Working with System.IO.Packaging
Open XML Developer Workshop
Lesson: Introduction to the Open Packaging
Convention
Open XML Formats Architecture
Components of the Open Packaging Convention
Open XML Developer Workshop
Elements of the Open Packaging Convention
Content Types Stream
Common Package Parts
Digital Signatures
Specific Format Parts
Office Document
Binary Part
XML Part
Part Rels
Part Relationships
Package Relationships
Core Properties
Package – The container
Document Parts – The
components of the document
Content Types Stream –
defines content type of parts
Relationships – references to
other parts of the document
“Start Part” – The root of the
document
Etc…
Open XML Developer Workshop
The Package
A package is
A logical entity that holds a collection of parts
An aggregation of all pieces of a document in a single
object
Not tied to a physical representation
ZIP, Database, loose files
Special features
Core properties
Thumbnail parts
Digital signatures
Open XML Developer Workshop
Document Parts
A part is
analogous to a file on the file system
stored inside the package in a specific location reachable via a URI
stored with a specific content type
mainly XML but other native types as well
Images, sounds, video, OLE objects
Content type is enforced
Example: cannot tag JPEG part as GIF
A part can use growth hints to allow uninterrupted
content growth
Open XML Developer Workshop
Content Types
• Define the type of media stored in the part.
The content types stream
Defines mappings from part to content type
Is not directly addressable
Default values and part specific overrides
[Content_Types].xml
Defaults
Overrides
<?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.openxmlformatsofficedocument.wordprocessingml.document.main+xml"/>
</Types>
Open XML Developer Workshop
Relationships
Relationships are stored in XML streams in the package
Ties elements inside the package to each other
Allows navigation of document without parsing parts
Package relationships stream URI: /_rels/.rels
Part relationships stream URI: _rels/[partname].rels
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
Relationship ID
Relationship Type
Target URI
<Relationships
xmlns="http://schemas.openxmlformats.org/package/2006/relation
ships">
<Relationship
Id=“rId1“
Type="http://schemas.openxmlformats.org/officeDocument
/2006/relationships/officeDocument"
Target="document.xml"/>
</Relationships>
Open XML Developer Workshop
Relationships
A relationship has its own type
The type gives meaning to the content in a part for a given context
A way to say “The styles part is stored at that location”
Part URI
Part content type
/document.xml
…wordprocessingml.document.main+xml
_rels/document.xml.rels
Rel. type
Target URI
Part URI
Part content type
http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles
/styles.xml
/styles.xml
…wordprocessingml.styles+xml
Open XML Developer Workshop
Inside an Open XML Package
Open XML Developer Workshop
Identifying the OfficeDocument “start part”
The OPC Package
Your
Code
Content Type Stream
[Content_Types].xml
Package Relationships
/_rels/.rels
GetRelationship (Rel.Type) : “http://schemas.../officeDocument”
PartUri : “/document.xml”
GetContentType (PartUri) : “/documents.xml”
Default extension
or URI override
ContentType :
“application/vnd…wordprocessingml.document.main+xml”
GetPart (PartUri) : “/document.xml”
Part: XML
Open XML Developer Workshop
Office Document Part
e.g. /document.xml
Identifying implicitly related parts
The OPC Package
Your
Code
Content Type Stream
[Content_Types].xml
Doc.Part
document.xml
Part Relationships
/_rels/document.xml.rels
Related Part
/styles.xml
GetRelationship (Rel.Type): “http://schemas.../styles”
GetRelationship (Rel.Type): “http://schemas.../styles”
PartUri : “/styles.xml”
PartUri : “/styles.xml”
GetContentType (PartUri): “/styles.xml”
Default extension
or URI override
ContentType:
“application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml”
GetPart (PartUri): “/styles.xml”
Part: XML
Open XML Developer Workshop
Identifying explicitly related parts
The OPC Package
Your
Code
Content Type Stream
[Content_Types].xml
Doc.Part
document.xml
Part Relationships
/_rels/document.xml.rels
GetRelationship (Rel.ID): “rId1”
GetRelationship (Rel.ID): “rId1”
PartUri : “/pict.png”
PartUri : “/pict.png”
GetPartType (PartUri): “/pict.png”
Default extension
or URI override
ContentType (Default extension or Override Uri):
“image/png”
GetPart (PartUri): “/pict.png”
Part: Binary
Open XML Developer Workshop
Related Part
/pict.png
Package Explorer
Open source tool written by Wouter van Vugt
http://www.codeplex.com/
Open XML Developer Workshop
Lesson: Working with System.IO.Packaging
Components of System.IO.Packaging
Traversing a Package
Manipulating a Package
Open XML Password Hashing
Open XML Developer Workshop
Components of System.IO.Packaging
The library
Part of Windows Presentation Foundation
Installed with .NET 3.0
Requires .NET 2.0 Runtime
Enables package manipulation for
Open XML File Formats
XML Paper Specification Files
Any Open Packaging Convention files
Open XML Developer Workshop
Components of System.IO.Packaging
The Package
Core Properties
Digital Signatures
Open XML Developer Workshop
Specific Format Parts
Office Document
XML Part
XML Part
Part Rels
Part Relationships
Package
Package Properties
PackageRelationships
PackageParts
Common Package Parts
Package Relationships
Package class provides
methods to create,
enumerate and delete
the following entities
Etc…
Components of System.IO.Packaging
The PackageRelationship
Core Properties
Digital Signatures
Open XML Developer Workshop
Specific Format Parts
Office Document
XML Part
XML Part
Part Rels
Part Relationships
ID
Package
RelationshipType
SourceUri
TargetMode
TargetUri
Common Package Parts
Package Relationships
Required to find parts (part
names are not guaranteed)
Iterate through a
RelationshipCollection by
type or ID
Relationship Properties
Etc…
Components of System.IO.Packaging
The PackagePart
Core Properties
Digital Signatures
Open XML Developer Workshop
Specific Format Parts
Office Document
XML Part
XML Part
Part Rels
Part Relationships
CompressionOption
ContentType
Package
Uri
Common Package Parts
Package Relationships
A PackagePart is the object
of data within the Package
It provides support to
create, enumerate and
delete part relationships
Get data as a
System.IO.Stream
PackagePart properties:
Etc…
Components of System.IO.Packaging
The PackUriHelper
Find a related PackagePart by searching relationships,
either by relationship type or relationship ID
This returns a list of PackageRelationship objects
A PackageRelationship defines two relative URIs
Source URI, pointing to the source PackagePart
Target URI, pointing to the target PackagePart
Retrieve a PackagePart by using a URI relative to the root
of the Package
Translation of Source and Target URIs is required
Use the PackUriHelper class to aid in the translation
Open XML Developer Workshop
Traversing a Package
Opening the “Start-Part”
<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>
Open XML Developer Workshop
Traversing a Package
Opening the “Start-Part”
<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>
Open XML Developer Workshop
Traversing a Package
Opening the “Start-Part”
Now using the Packaging API
string 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
}
Open XML Developer Workshop
Traversing a Package
Opening a related document part
<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>
Open XML Developer Workshop
Traversing a Package
Opening a related document part
<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/drawi
ngml/2006/main"
name="Office Theme">
<a:themeElements>
<a:clrScheme name="Office">
<a:dk1>
<a:sysClr val="windowText" lastClr="000000" />
</a:dk1>
Open XML Developer Workshop
Traversing a Package
Opening a related document part
You can retrieve a Part using a relationshipID
string relID= “rId1”;
PackageRelationship imagerelationship = mainPart.GetRelationship(relID);
Uri imagePartUri = PackUriHelper.ResolvePartUri(
imagerelationship.SourceUri, imagerelationship.TargetUri);
PackagePart imagepart = mainPart.Package.GetPart(imagePartUri);
Or using the relationshipType
string RT_Image = “http://schemas.openxmlformats.org/.../image”;
int imageCount = 0;
foreach (PackageRelationship relation in
mainPart.GetRelationshipsByType(RT_Image))
{
imageCount++;
}
Console.WriteLine("The part references {0} unique images", imageCount);
Open XML Developer Workshop
Traversing a Package
Open XML Developer Workshop
Creating a New Package
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
}
Open XML Developer Workshop
Creating a Part
Create a PackagePart using
Location (Uri)
Content type (String)
You can not alter the content type later on
Make sure the location is not in use
Use a Stream to modify the PackagePart contents
string contentType = “application/vnd.openxmlformatsofficedocument.spreadsheetml.sheet.main+xml”;
PackagePart part = package.CreatePart(
new Uri(“workbook.xml”, UriKind.Relative), contentType);
using (StreamWriter writer = new StreamWriter(
part.GetStream(FileMode.Create, FileAccess.Write)))
{
using (StreamReader reader = new StreamReader(path))
{
writer.Write(reader.ReadToEnd());
}
}
Open XML Developer Workshop
Creating Part Relationships
Each PackagePart needs to be related to its child parts
Relationship ID, RelationshipType, TargetMode
using (Package package = Package.Open("newFile.xlsx",
FileMode.OpenOrCreate, FileAccess.ReadWrite))
{
PackagePart workbook = package.CreatePart(
new Uri(“/workbook.xml”, UriKind.Relative),
“application/vnd...sheet.main+xml”);
PackagePart sheet = package.CreatePart(
new Uri(“/sheet1.xml”, UriKind.Relative),
“application/vnd...worksheet.main+xml”, package);
Start
Part
package.CreateRelationship(
new Uri("/workbook.xml", UriKind.Relative), TargetMode.Internal,
"http://schemas.../relationships/officeDocument", "rId1");
Related
Part
workbook.CreateRelationship(
new Uri("/sheet1.xml", UriKind.Relative), TargetMode.Internal,
"http://schemas.../relationships/worksheet", "rId1");
}
Open XML Developer Workshop
Digital Signatures
Digital Signatures in the Package
Allows the validation of package integrity using X.509 certificates
You can sign
All parts, including digital signatures
All relationships, or a subset of a set of relationships
Navigate signatures with the Digital Signature Origin Part
Open XML Developer Workshop
Digital Signatures
Digital
Signature
Origin Part
Relationship
Digital Signature
XML Signature
Part
URI
URI
Relationship
Digital Signature
XML Signature
Part
X.509
URI
URI
Signed Part
Signed Part
Signed Part
X.509
Certificate
Part
Open XML Developer Workshop
Signed Part
Microsoft SDK for Open XML Formats
Microsoft.Office.DocumentFormat.OpenXml
Library of strongly typed parts:
Document start part, styles part, etc.
Classes for Open XML elements
Consistent high-level interface
To the packaging API, “parts is parts”
To the SDK for Open XML, each part has a type based on
its content and markup structure
Open XML Developer Workshop
SDK Code Sample
// How to: Replace a part in a package.
public static void ReplaceTheme(string document, string themeFile)
{
using (WordprocessingDocument wordDoc =
WordprocessingDocument.Open(document, true))
{
MainDocumentPart mainPart = wordDoc.MainDocumentPart;
// Delete the old part.
mainPart.DeletePart(mainPart.ThemePart);
// Add a new part and then add content.
ThemePart themePart = mainPart.AddNewPart<ThemePart>( );
using (StreamReader streamReader = new
StreamReader(themeFile))
using (StreamWriter streamWriter = new StreamWriter(
themePart.GetStream(FileMode.Create ) ))
{
streamWriter.Write(streamReader.ReadToEnd( ));
}
}
}
See LAB08 and LAB08SDK for a comparison of the SDK and
System.IO.Packaging.
Open XML Developer Workshop
Where to get the SDK for Open XML
Download the June CTP:
http://www.microsoft.com/downloads/details.aspx?FamilyId=AD0B72FB4A1D-4C52-BDB5-7DD7E816D046&displaylang=en
MSDN documentation:
http://msdn2.microsoft.com/en-us/library/bb448854.aspx
MSDN support forum:
http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=1647&Site
ID=1
Open XML Developer Workshop
How to think about OPC packages
Files and folders – NO!
Parts and relationships – YES
Open XML Developer Workshop
Resources
OpenXMLDeveloper.org
Kevin Boske’s blog
http://blogs.msdn.com/kevinboske
Brian Jones’s blog
http://blogs.msdn.com/brian_jones
Doug Mahugh’s blog
http://blogs.msdn.com/dmahugh
XPS Blog:
http://blogs.msdn.com/xps
Open XML Developer Workshop
Open XML Developer Workshop