Package.CreateRelationship 方法

定義

命名空間:

System.IO.Packaging

組件:

System.IO.Packaging.dll

套件:

System.IO.Packaging v8.0.0

建立特定組件的套件層級關係。

多載

CreateRelationship(Uri, TargetMode, String)	以特定 URI、目標模式及關聯性類型建立套件層級關係。
CreateRelationship(Uri, TargetMode, String, String)	建立具有指定 URI、目標模式、關聯性類型和識別碼 (識別碼) 之元件的套件層級關聯性。

範例

下列範例說明 PackageRelationship 在 Package 與根檔案元件之間建立 。 如需完整的範例，請參閱 撰寫套件範例。

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

備註

套件層級關聯性會定義封裝與相關聯目標元件或資源之間的關聯。 套件層級關聯性可以是兩種形式之一。

• 在 Package 封裝內的目標 PackagePart 之間。

• 在 Package 封裝外部的目標資源之間。

在套件關聯性中，封裝會被視為關聯性的「擁有者」。 刪除封裝時，也會刪除封裝所擁有的所有關聯性。 建立或刪除關聯性的程式不會以任何方式實際改變目標元件或資源。

如需詳細資訊，請參閱可在 下載 https://www.ecma-international.org/publications-and-standards/standards/ecma-376/的開放封裝慣例 (OPC) 規格。

CreateRelationship(Uri, TargetMode, String)

來源:

Package.cs

以特定 URI、目標模式及關聯性類型建立套件層級關係。

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

參數

targetUri

Uri

目標組件的統一資源識別項 (URI)。

targetMode

TargetMode

指出目標組件是套件的 Internal 或 External。

relationshipType

String

唯一定義關聯性角色的 URI。

傳回

PackageRelationship

指定之組件的套件層級關係。

例外狀況

ArgumentNullException

targetUri 或 relationshipType 為 null。

ArgumentException

targetUri 組件是 PackageRelationship，或 targetMode 是 Internal 且 targetUri 是絕對 URI。

ArgumentOutOfRangeException

targetMode 的值無效。

ObjectDisposedException

套件沒有開啟 (已呼叫 Dispose(Boolean) 或 Close())。

IOException

封裝是唯讀的。

範例

下列範例說明如何使用 CreateRelationship 在 PackageRelationship 與根文件元件之間建立 Package 。 如需完整的範例，請參閱 撰寫套件範例。

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

備註

套件層級關聯性會定義封裝與相關聯目標元件或資源之間的關聯。 套件層級關聯性可以是兩種形式之一。

• 在封裝 Package 中的目標元件之間。

• 在 Package 封裝外部的目標資源之間。

在套件關聯性中，封裝會被視為關聯性的「擁有者」。 刪除封裝時，也會刪除封裝所擁有的所有關聯性。

CreateRelationship 不會以任何方式實際變更目標元件或資源。

關聯性的目標不能是另一個關聯性。

如果 targetMode 指定為 Internal， targetUri 則必須根據 RFC 3986 統一資源標識碼 (URI) 一般語法規格來形成相對 URI。 內部相對 URI 可以是以正斜線開頭的絕對路徑， (“/”) 字元，例如 “/page1.xaml” 或 “/images/picture4.jpg”，或 “.. 等相對路徑。/imagespicture1.jpg“，針對封裝根目錄 (”/“) 解析為基底 URI。

如果 targetMode 指定為 External， targetUri 則可以根據 RFC 3986 統一資源標識碼 (URI) 一般語法規格來形成絕對或相對 URI。 http://www.microsoft.com/page2.xml 是參考外部目標資源 「page2.xml」 的絕對 URI 範例。 “images/picture1.jpg” 是相對 URI 的範例，它也會參考外部目標資源 “1.jpg”，但會根據封裝本身的 URI 解析。

relationshipType 必須是根據 RFC 3986 統一資源識別元 (URI) 一般語法規格所構成的 URI。 下表顯示開放封裝慣例所定義的套件層級 relationshipType URI (OPC) 規格。

套件層級關聯性	關聯性類型 URI
核心屬性	http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties
數位簽章	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature
數字簽名憑證	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/certificate
數位簽名來源	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/origin
縮圖	http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail

如需封裝和套件關聯性的詳細資訊，請參閱開放封裝慣例 (OPC) 規格的 1.3 節，可在 下載 https://www.ecma-international.org/publications-and-standards/standards/ecma-376/。

另請參閱

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

CreateRelationship(Uri, TargetMode, String, String)

來源:

Package.cs

建立具有指定 URI、目標模式、關聯性類型和識別碼 (識別碼) 之元件的套件層級關聯性。

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

參數

targetUri

Uri

目標組件的統一資源識別項 (URI)。

targetMode

TargetMode

指出目標組件是套件的 Internal 或 External。

relationshipType

String

唯一定義關聯性角色的 URI。

id

String

唯一的 XML 識別項。

傳回

PackageRelationship

指定之組件的套件層級關係。

例外狀況

ArgumentNullException

targetUri 或 relationshipType 為 null。

ArgumentException

targetUri 組件是 PackageRelationship，或 targetMode 是 Internal 且 targetUri 是絕對 URI。

ArgumentOutOfRangeException

targetMode 的值無效。

ObjectDisposedException

套件沒有開啟 (已呼叫 Dispose(Boolean) 或 Close())。

IOException

封裝是唯讀的。

XmlException

id 不是有效的 XML 識別項，或是套件中已存在具有指定之 id 的組件。

範例

下列範例說明如何使用 CreateRelationship 在 PackageRelationship 與根文件元件之間建立 Package 。 如需完整的範例，請參閱 撰寫套件範例。

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

備註

套件層級關聯性會定義封裝與相關聯目標元件或資源之間的關聯。 套件層級關聯性可以是兩種形式之一。

• 在封裝 Package 中的目標元件之間。

• 在 Package 封裝外部的目標資源之間。

在套件關聯性中，封裝會被視為關聯性的「擁有者」。 刪除封裝時，也會刪除封裝所擁有的所有關聯性。

CreateRelationship 不會以任何方式實際變更目標元件或資源。

關聯性的目標不能是另一個關聯性。

id 必須是有效的 XML 識別碼。 此 id 類型為 xsd：ID，且必須遵循 XML 架構第 2 部分：資料類型規格中指定的命名慣例， (請參閱 https://www.w3.org/TR/xmlschema-2/#ID) 。

如果 id 指定為 null 唯一標識碼，將會自動產生。 id空字串所指定的 無效。

如果 targetMode 指定為 Internal， targetUri 則必須根據 RFC 3986 統一資源標識碼 (URI) 一般語法規格來形成相對 URI。 內部相對 URI 可以是以正斜線開頭的絕對路徑， (“/”) 字元，例如 “/page1.xaml” 或 “/images/picture4.jpg”，或 “.. 等相對路徑。/imagespicture1.jpg“，針對封裝根目錄 (”/“) 解析為基底 URI。

如果 targetMode 指定為 External， targetUri 則可以根據 RFC 3986 統一資源標識碼 (URI) 一般語法規格來形成絕對或相對 URI。 http://www.microsoft.com/page2.xml 是參考外部目標資源 「page2.xml」 的絕對 URI 範例。 “images/picture1.jpg” 是相對 URI 的範例，它也會參考外部目標資源 “1.jpg”，但會根據封裝本身的 URI 解析。

relationshipType 必須是根據 RFC 3986 統一資源識別元 (URI) 一般語法規格所構成的 URI。 下表顯示開放封裝慣例所定義的套件層級 relationshipType URI (OPC) 規格。

套件層級關聯性	關聯性類型 URI
核心屬性	http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties
數位簽章	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature
數字簽名憑證	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/certificate
數位簽名來源	http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/origin
縮圖	http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail

如需封裝和套件關聯性的詳細資訊，請參閱開放封裝慣例 (OPC) 規格的 1.3 節，以下載。https://www.ecma-international.org/publications-and-standards/standards/ecma-376/

另請參閱

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