Bewerken

Share via


PackagePart.CreateRelationship Method

Definition

Creates a part-level relationship between this PackagePart to a specified target PackagePart or external resource.

Overloads

CreateRelationship(Uri, TargetMode, String)

Creates a part-level relationship between this PackagePart to a specified target PackagePart or external resource.

CreateRelationship(Uri, TargetMode, String, String)

Creates a part-level relationship between this PackagePart to a specified target PackagePart or external resource.

Remarks

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

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

The CreateRelationship method does not physically change either the source part, or the target part or resource in any way.

The target of a relationship cannot be another relationship.

For more information about 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/.

For more information about XPS documents, see the Open XML Paper Specification (XPS) available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-388/.

CreateRelationship(Uri, TargetMode, String)

Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs

Creates a part-level relationship between this PackagePart to a specified target PackagePart or external resource.

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 URI of the target part.

targetMode
TargetMode

One of the enumeration values. For example, Internal if the target part is inside the Package; or External if the target is a resource outside the Package.

relationshipType
String

The role of the relationship.

Returns

The part-level relationship between this PackagePart to the target PackagePart or external resource.

Exceptions

The part has been deleted.

-or-

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

targetUri or relationshipType is null.

The targetMode parameter is not a valid TargetMode enumeration value.

The part identified by the targetUri is a relationship (the target of a relationship cannot be another relationship).

-or-

targetMode is specified as Internal but targetUri is an absolute external URI.

The package is read-only (a new relationship cannot be added).

Remarks

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

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

The CreateRelationship method does not physically change either the source part, or 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 in accordance with 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 in accordance with the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. "https://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. Different package types can define different part-level relationship types. The following table shows the part-level relationshipType URIs defined for documents that conform to the Open XML Paper Specification (XPS).

XPS Document Part-Level Relationship Relationship Type URI
Digital Signature Definitions http://schemas.microsoft.com/xps/2005/06/signature-definitions
DiscardControl http://schemas.microsoft.com/xps/2005/06/discard-control
DocumentStructure http://schemas.microsoft.com/xps/2005/06/documentstructure
PrintTicket http://schemas.microsoft.com/xps/2005/06/printticket
Required Resource http://schemas.microsoft.com/xps/2005/06/required-resource
Restricted Font http://schemas.microsoft.com/xps/2005/06/restricted-font
StartPart http://schemas.microsoft.com/xps/2005/06/fixedrepresentation
StoryFragments http://schemas.microsoft.com/xps/2005/06/storyfragments

For more information about 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/.

For more information about XPS documents, see the Open XML Paper Specification (XPS) available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-388/.

See also

Applies to

CreateRelationship(Uri, TargetMode, String, String)

Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs
Source:
PackagePart.cs

Creates a part-level relationship between this PackagePart to a specified target PackagePart or external resource.

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);
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 URI of the target part.

targetMode
TargetMode

One of the enumeration values. For example, Internal if the target part is inside the Package; or External if the target is a resource outside the Package.

relationshipType
String

The role of the relationship.

id
String

A unique ID for the relationship.

Returns

The part-level relationship between this PackagePart to the target PackagePart or external resource.

Exceptions

The part has been deleted.

-or-

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

targetUri or relationshipType is null.

The targetMode parameter is not a valid TargetMode enumeration value.

The part identified by the targetUri is a relationship (the target of a relationship cannot be another relationship).

-or-

targetMode is specified as Internal but targetUri is an absolute external URI.

The package is read-only (a new relationship cannot be added).

id is not a valid XML identifier.

-or-

A part with the specified id already exists.

Remarks

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

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

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).

The CreateRelationship method does not physically change either the source part, or 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 in accordance with 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 in accordance with the RFC 3986 Uniform Resource Identifier (URI) Generic Syntax specification. "https://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. Different package types can define different part-level relationship types. The following table shows the part-level relationshipType URIs defined for documents that conform to the Open XML Paper Specification (XPS).

XPS Document Part-Level Relationship Relationship Type URI
Digital Signature Definitions http://schemas.microsoft.com/xps/2005/06/signature-definitions
DiscardControl http://schemas.microsoft.com/xps/2005/06/discard-control
DocumentStructure http://schemas.microsoft.com/xps/2005/06/documentstructure
PrintTicket http://schemas.microsoft.com/xps/2005/06/printticket
Required Resource http://schemas.microsoft.com/xps/2005/06/required-resource
Restricted Font http://schemas.microsoft.com/xps/2005/06/restricted-font
StartPart http://schemas.microsoft.com/xps/2005/06/fixedrepresentation
StoryFragments http://schemas.microsoft.com/xps/2005/06/storyfragments

For more information about 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/.

For more information about XPS documents see the Open XML Paper Specification (XPS) available for download at https://www.ecma-international.org/publications-and-standards/standards/ecma-388/.

See also

Applies to