Package.CreateRelationship Method

Definition

Namespace:

System.IO.Packaging

Assembly:

System.IO.Packaging.dll

Creates a package-level relationship to a given part.

Overloads

CreateRelationship(Uri, TargetMode, String)	Creates a package-level relationship to a part with a given URI, target mode, and relationship type.
CreateRelationship(Uri, TargetMode, String, String)	Creates a package-level relationship to a part with a given URI, target mode, relationship type, and identifier (ID).

Examples

The following example illustrates creating a PackageRelationship between a Package and a root document part.

// Add the Document part to the Package
PackagePart packagePartDocument =
    package.CreatePart(partUriDocument,
                   System.Net.Mime.MediaTypeNames.Text.Xml);

// Copy the data to the Document Part
using (FileStream fileStream = new FileStream(
       documentPath, FileMode.Open, FileAccess.Read))
{
    CopyStream(fileStream, packagePartDocument.GetStream());
}// end:using(fileStream) - Close and dispose fileStream.

// Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri,
                           TargetMode.Internal,
                           PackageRelationshipType);

' Add the Document part to the Package
Dim packagePartDocument As PackagePart = package.CreatePart(partUriDocument, System.Net.Mime.MediaTypeNames.Text.Xml)

' Copy the data to the Document Part
Using fileStream As New FileStream(documentPath, FileMode.Open, FileAccess.Read)
    CopyStream(fileStream, packagePartDocument.GetStream())
End Using ' end:using(fileStream) - Close and dispose fileStream.

' Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri, TargetMode.Internal, PackageRelationshipType)

Remarks

A package-level relationship defines an association between the package and an associated target part or resource. A package-level relationship can be one of two forms.

• Between a Package to a target PackagePart inside the package.
• Between a Package to a target resource outside the package.

In a package-relationship the package is considered the "owner" of the relationship. When the package is deleted, all the relationships owned by the package are also deleted. The process of creating or deleting the relationship does not physically alter the target part or resource in any way.

For additional information, see the Open Packaging Conventions (OPC) specification available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-376/.

CreateRelationship(Uri, TargetMode, String)

Creates a package-level relationship to a part with a given URI, target mode, and relationship type.

public:
 System::IO::Packaging::PackageRelationship ^ CreateRelationship(Uri ^ targetUri, System::IO::Packaging::TargetMode targetMode, System::String ^ relationshipType);

public System.IO.Packaging.PackageRelationship CreateRelationship (Uri targetUri, System.IO.Packaging.TargetMode targetMode, string relationshipType);

member this.CreateRelationship : Uri * System.IO.Packaging.TargetMode * string -> System.IO.Packaging.PackageRelationship

Public Function CreateRelationship (targetUri As Uri, targetMode As TargetMode, relationshipType As String) As PackageRelationship

Parameters

targetUri

Uri

The uniform resource identifier (URI) of the target part.

targetMode

TargetMode

Indicates if the target part is Internal or External to the package.

relationshipType

String

A URI that uniquely defines the role of the relationship.

Returns

PackageRelationship

The package-level relationship to the specified part.

Exceptions

ArgumentNullException

targetUri or relationshipType is null.

ArgumentException

The targetUri part is a PackageRelationship, or targetMode is Internal and targetUri is an absolute URI.

ArgumentOutOfRangeException

The value for targetMode is not valid.

ObjectDisposedException

The package is not open (Dispose(Boolean) or Close() has been called).

IOException

The package is read-only.

Examples

The following example illustrates how to use CreateRelationship to create a PackageRelationship between a Package and a root document part.

// Add the Document part to the Package
PackagePart packagePartDocument =
    package.CreatePart(partUriDocument,
                   System.Net.Mime.MediaTypeNames.Text.Xml);

// Copy the data to the Document Part
using (FileStream fileStream = new FileStream(
       documentPath, FileMode.Open, FileAccess.Read))
{
    CopyStream(fileStream, packagePartDocument.GetStream());
}// end:using(fileStream) - Close and dispose fileStream.

// Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri,
                           TargetMode.Internal,
                           PackageRelationshipType);

' Add the Document part to the Package
Dim packagePartDocument As PackagePart = package.CreatePart(partUriDocument, System.Net.Mime.MediaTypeNames.Text.Xml)

' Copy the data to the Document Part
Using fileStream As New FileStream(documentPath, FileMode.Open, FileAccess.Read)
    CopyStream(fileStream, packagePartDocument.GetStream())
End Using ' end:using(fileStream) - Close and dispose fileStream.

' Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri, TargetMode.Internal, PackageRelationshipType)

Remarks

A package-level relationship defines an association between the package and an associated target part or resource. A package-level relationship can be one of two forms.

• Between a Package to a target part in the package.
• Between a Package to a target resource outside the package.

In a package-relationship the package is considered the "owner" of the relationship. When the package is deleted, all the relationships owned by the package are also deleted.

CreateRelationship does not physically change the target part or resource in any way.

The target of a relationship cannot be another relationship.

If targetMode is specified as Internal, targetUri must be a relative URI that is formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. The internal relative URI can be either an absolute path that starts with a forward slash ("/") character such as "/page1.xaml" or "/images/picture4.jpg", or a relative path such as "../imagespicture1.jpg" that resolves against the package root ("/") as the base URI.

If targetMode is specified as External, targetUri can be either an absolute or relative URI formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. http://www.microsoft.com/page2.xml is an example of an absolute URI that references an external target resource "page2.xml". "images/picture1.jpg" is an example of a relative URI that also references an external target resource "1.jpg" but which resolves against the URI of the package itself.

relationshipType must be a URI that is formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. The following table shows the package-level relationshipType URIs defined by the Open Packaging Conventions (OPC) specification.

Package-level Relationship	Relationship Type URI
Core Properties	http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties
Digital Signature	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature
Digital Signature Certificate	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/certificate
Digital Signature Origin	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/origin
Thumbnail	http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail

For more information about packaging and package relationships, see section 1.3 of the Open Packaging Conventions (OPC) specification available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-376/.

See also

• DeleteRelationship(String)
• GetRelationship(String)
• GetRelationships()
• GetRelationshipsByType(String)
• RelationshipExists(String)

CreateRelationship(Uri, TargetMode, String, String)

Creates a package-level relationship to a part with a given URI, target mode, relationship type, and identifier (ID).

public:
 System::IO::Packaging::PackageRelationship ^ CreateRelationship(Uri ^ targetUri, System::IO::Packaging::TargetMode targetMode, System::String ^ relationshipType, System::String ^ id);

public System.IO.Packaging.PackageRelationship CreateRelationship (Uri targetUri, System.IO.Packaging.TargetMode targetMode, string relationshipType, string? id);

member this.CreateRelationship : Uri * System.IO.Packaging.TargetMode * string * string -> System.IO.Packaging.PackageRelationship

Public Function CreateRelationship (targetUri As Uri, targetMode As TargetMode, relationshipType As String, id As String) As PackageRelationship

Parameters

targetUri

Uri

The uniform resource identifier (URI) of the target part.

targetMode

TargetMode

Indicates if the target part is Internal or External to the package.

relationshipType

String

A URI that uniquely defines the role of the relationship.

id

String

A unique XML identifier.

Returns

PackageRelationship

The package-level relationship to the specified part.

Exceptions

ArgumentNullException

targetUri or relationshipType is null.

ArgumentException

The targetUri part is a PackageRelationship, or targetMode is Internal and targetUri is an absolute URI.

ArgumentOutOfRangeException

The value for targetMode is not valid.

ObjectDisposedException

The package is not open (Dispose(Boolean) or Close() has been called).

IOException

The package is read-only.

XmlException

id is not a valid XML identifier; or a part with the specified id already occurs in the package.

Examples

The following example illustrates how to use CreateRelationship to create a PackageRelationship between a Package and a root document part.

// Add the Document part to the Package
PackagePart packagePartDocument =
    package.CreatePart(partUriDocument,
                   System.Net.Mime.MediaTypeNames.Text.Xml);

// Copy the data to the Document Part
using (FileStream fileStream = new FileStream(
       documentPath, FileMode.Open, FileAccess.Read))
{
    CopyStream(fileStream, packagePartDocument.GetStream());
}// end:using(fileStream) - Close and dispose fileStream.

// Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri,
                           TargetMode.Internal,
                           PackageRelationshipType);

' Add the Document part to the Package
Dim packagePartDocument As PackagePart = package.CreatePart(partUriDocument, System.Net.Mime.MediaTypeNames.Text.Xml)

' Copy the data to the Document Part
Using fileStream As New FileStream(documentPath, FileMode.Open, FileAccess.Read)
    CopyStream(fileStream, packagePartDocument.GetStream())
End Using ' end:using(fileStream) - Close and dispose fileStream.

' Add a Package Relationship to the Document Part
package.CreateRelationship(packagePartDocument.Uri, TargetMode.Internal, PackageRelationshipType)

Remarks

A package-level relationship defines an association between the package and an associated target part or resource. A package-level relationship can be one of two forms.

• Between a Package to a target part in the package.
• Between a Package to a target resource outside the package.

In a package-relationship the package is considered the "owner" of the relationship. When the package is deleted, all the relationships owned by the package are also deleted.

CreateRelationship does not physically change the target part or resource in any way.

The target of a relationship cannot be another relationship.

id must be a valid XML identifier. The id type is xsd:ID and must follow the naming conventions prescribed in the XML Schema Part 2: Datatypes specification (see https://www.w3.org/TR/xmlschema-2/#ID).

If id is specified as null a unique ID will be automatically generated. An id specified by an empty string is not valid.

If targetMode is specified as Internal, targetUri must be a relative URI that is formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. The internal relative URI can be either an absolute path that starts with a forward slash ("/") character such as "/page1.xaml" or "/images/picture4.jpg", or a relative path such as "../imagespicture1.jpg" that resolves against the package root ("/") as the base URI.

If targetMode is specified as External, targetUri can be either an absolute or relative URI formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. http://www.microsoft.com/page2.xml is an example of an absolute URI that references an external target resource "page2.xml". "images/picture1.jpg" is an example of a relative URI that also references an external target resource "1.jpg" but which resolves against the URI of the package itself.

relationshipType must be a URI that is formed according to the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. The following table shows the package-level relationshipType URIs defined by the Open Packaging Conventions (OPC) specification.

Package-level Relationship	Relationship Type URI
Core Properties	http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties
Digital Signature	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature
Digital Signature Certificate	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/certificate
Digital Signature Origin	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/origin
Thumbnail	http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail

For additional information about packaging and package relationships, see section 1.3 of the Open Packaging Conventions (OPC) specification available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-376/.

See also

• CreateRelationship(Uri, TargetMode, String)
• DeleteRelationship(String)
• GetRelationship(String)
• GetRelationships()
• GetRelationshipsByType(String)
• RelationshipExists(String)