XML Manifest File Format
The XML manifest file describes the contents of the package and specifies how the contents of the package are mapped into a directory structure for each role. Commonly, a file that is deployed for a given role is needed in other roles. The single manifest in the new package format allows the creator to include the duplicated file exactly once and then declaratively describe how to deploy that file to multiple roles. The new package format simplifies the archive structure and allows package creators to optimize archives that share files across roles or within a role. This results in a smaller package size that can enable faster deployment to Windows Azure.
By convention, the XML manifest file is named package.xml. However, the XML manifest can be any file in the archive as long as the relationship points to the XML manifest file and the XML manifest file conforms to the schema.
This topic describes the format of the XML manifest file by using examples. To view the schema of the XML manifest file, see XML Manifest File Schema.
The basic XML format is as follows:
<?xml version="1.0" encoding="utf-8"?>
<PackageDefinition xmlns:i="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://schemas.microsoft.com/windowsazure">
<PackageMetaData />
<PackageContents />
<PackageLayouts />
</PackageDefinition>
The following is the XML namespace for the XML manifest file:
https://schemas.microsoft.com/windowsazure
The XML manifest contains three sections. Each section is a collection of named resources wherein all of the names are relative URIs by the use of “a/b/c…” syntax. These names are treated as case sensitive when determining equality and should follow the normal URI encoding and escaping conventions. This topic describes each of the three sections in sequence as follows:
PackageMetaData
PackageContents
PackageLayouts
PackageMetaData
The PackageMetaData collection is a key/value store, where the keys are strings and the values are strings. The following is an example of a PackageMetaData collection:
<PackageMetaData>
<KeyValuePair>
<Key>https://schemas.microsoft.com/windowsazure/ProductVersion/</Key>
<Value>1.7.30308.2000 </Value>
</KeyValuePair>
</PackageMetaData>
The sum of the UTF-8 bytes that encode the key and values must not exceed 1MB. Package processors with more than 1 MB of metadata can be rejected by any package processor.
To avoid namespace conflicts, metadata keys should be URIs that follow the same conventions as used by XML name spaces.
PackageContents
The PackageContents collection describes the files that comprise the package. This includes file name, length, an optional sha256 hash of the contents, and path. The following is an example of a PackageContents collection:
<PackageContents>
<ContentDefinition>
<Name>Content/Example/WithoutHash</Name>
<ContentDescription>
<LengthInBytes>123</LengthInBytes>
<IntegrityCheckHashAlgortihm>None</IntegrityCheckHashAlgortihm>
<IntegrityCheckHash/>
<DataStorePath>File00</DataStorePath>
</ContentDescription>
</ContentDefinition>
<ContentDefinition>
<Name>Content/Example/WithHash</Name>
<ContentDescription>
<LengthInBytes>123</LengthInBytes>
<IntegrityCheckHashAlgortihm>Sha256</IntegrityCheckHashAlgortihm> <IntegrityCheckHash>AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=</IntegrityCheckHash>
<DataStorePath>File01</DataStorePath>
</ContentDescription>
</ContentDefinition>
</PackageContents>
A content item is a named stream of bytes and content blob resources that can be of unlimited size. This stream of bytes can optionally have an integrity check to verify that the bytes were properly transported without corruption.
The valid values for the IntegrityCheckHashAlgortihm element are None and Sha256. If None is specified, then the IntegrityCheckHash element must be the empty element. For Sha256, the string should be a base-64 encoding of hash bytes. This string must be XSD type xs:base64Binary.
Names are relative URIs and are treated case sensitively. Each content item has a DataStorePath element, which is a relative URI that refers to the byte stream in the OPC archive for that item. The name of the DataStorePath is arbitrary. To ensure that OPC files can easily be unpacked and repacked on different file systems, OPC item names should be US-ASCII and should be unique when compared case insensitively. You should also use of short names in order to avoid file system path limits.
PackageLayouts
The PackageLayouts collection maps content resources to a particular layout of files and directories on a Windows Azure VM. The file layout includes the creation and modified times, as well as a relative path. The paths of should be considered specific to a given target file system. Since the syntax of the path is operating system dependent they should be treated as opaque values. Since layouts are simply a description of the mapping the size of a layout is proportional to the number of files in the layout and not the size of the contents. This means package authors in the future can potentially include alternative layouts; for example one layout that targets Linux and one layout that target Windows operating system, and then build operating system agnostic packages. For Windows Azure SDK 1.7, however, packages must follow Windows conventions.
The PackageLayouts collection maps package contents to a particular layout of files and directories on a Windows Azure virtual machine. Package layouts are named and a package can have several different layouts. Each layout describes how to extract the byte stream of a package content item into a file on a target file system. Each layout is a list of unique file paths using the naming conventions of the target file system. Package authors can potentially include alternative layouts and build operating system agnostic packages. For example, a package could include one layout that targets Linux and one layout that targets Windows. The layout also includes file meta-data, such as UTC creation and modification times and read-only attributes.
The following example of a PackageLayouts collection contains two layouts, named fileCollection1 and fileCollection2. Both of these layouts describe the creation of two files from the package resources Content/Example/WithoutHash and Content/Example/WithHash. However, they map the content to different file names. In fileCollection1, the file names are unique with respect to case. In fileCollection2, the names differ only by case. This example illustrates how the packaging format is designed to be agnostic, but that package authors creating file layouts must be aware of the target file system conventions. The second file layout, fileCollection2, can only be extracted on an operation system whose file system is case sensitive. In particular, the string encoded in the FilePath argument is treated as an opaque key compared case sensitively.
<PackageLayouts>
<LayoutDefinition>
<Name>fileColletion1</Name>
<LayoutDescription>
<FileDefinition>
<FilePath>Readme.txt</FilePath>
<FileDescription>
<DataContentReference>Content/Example/WithoutHash</DataContentReference>
<CreatedTimeUtc>2012-02-01T01:16:33.9633733Z</CreatedTimeUtc>
<ModifiedTimeUtc>2012-02-01T01:16:33.9643734Z</ModifiedTimeUtc>
<ReadOnly>false</ReadOnly>
</FileDescription>
</FileDefinition>
<FileDefinition>
<FilePath>ReadmeToo.txt</FilePath>
<FileDescription>
<DataContentReference>Content/Example/WithHash</DataContentReference>
<CreatedTimeUtc>2012-02-01T01:16:33.9643734Z</CreatedTimeUtc>
<ModifiedTimeUtc>2012-02-01T01:16:33.9643734Z</ModifiedTimeUtc>
<ReadOnly>false</ReadOnly>
</FileDescription>
</FileDefinition>
</LayoutDescription>
</LayoutDefinition>
<LayoutDefinition>
<Name>fileColletion2</Name>
<LayoutDescription>
<FileDefinition>
<FilePath>README</FilePath>
<FileDescription>
<DataContentReference>Content/Example/WithoutHash</DataContentReference>
<CreatedTimeUtc>2012-02-01T01:16:33.9643734Z</CreatedTimeUtc>
<ModifiedTimeUtc>2012-02-01T01:16:33.9643734Z</ModifiedTimeUtc>
<ReadOnly>false</ReadOnly>
</FileDescription>
</FileDefinition>
<FileDefinition>
<FilePath>Readme</FilePath>
<FileDescription>
<DataContentReference>Content/Example/WithHash</DataContentReference>
<CreatedTimeUtc>2012-02-01T01:16:33.9643734Z</CreatedTimeUtc>
<ModifiedTimeUtc>2012-02-01T01:16:33.9643734Z</ModifiedTimeUtc>
<ReadOnly>false</ReadOnly>
</FileDescription>
</FileDefinition>
</LayoutDescription>
</LayoutDefinition>
</PackageLayouts>