HOW TO:建立自訂宣告How to: Create a Custom Claim

Windows Communication Foundation (WCF)中的身分識別模型基礎結構會提供一組內建的宣告類型和許可權,其中包含用來建立 Claim 具有這些類型和許可權之實例的 helper 函數。The Identity Model infrastructure in Windows Communication Foundation (WCF) provides a set of built-in claim types and rights with the helper functions for creating Claim instances with those types and rights. 這些內建的宣告是設計用來根據預設支援的用戶端認證類型中的資訊模型。These built-in claims are designed to model information found in client credential types that WCF supports by default. 在許多情況下,內建宣告就已足夠;不過有些應用程式可能需要自訂宣告。In many cases, the built-in claims are sufficient; however some applications may require custom claims. 宣告中包含了宣告類型、宣告適用的資源,以及擁有該資源所需的權限。A claim consists of the claim type, the resource for which the claim applies to and the right that is asserted over that resource. 這個主題會描述如何建立自訂宣告。This topic describes how to create a custom claim.

依據基本資料型別建立自訂宣告To create a custom claim that is based on a primitive data type

  1. 將宣告類型、資源值和權限傳遞至 Claim(String, Object, String) 建構函式,即可建立自訂宣告。Create a custom claim by passing the claim type, resource value and right to the Claim(String, Object, String) constructor.

    1. 決定用於宣告類型的唯一值。Decide on a unique value for the claim type.

      宣告類型為唯一的字串識別碼。The claim type is a unique string identifier. 自訂宣告設計者的責任在於確保用於宣告類型的字串識別碼為獨一無二的。It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. 如需 WCF 所定義的宣告類型清單,請參閱 ClaimTypes 類別。For a list of claim types that are defined by WCF, see the ClaimTypes class.

    2. 選擇基本資料型別和資源的值。Choose the primitive data type and value for the resource.

      資源就是物件。A resource is an object. 資源的 CLR 類型可以為基本,例如 StringInt32,或任何可序列化的類型。The CLR type of the resource can be a primitive, such as String or Int32, or any serializable type. 資源的 CLR 類型必須是可序列化的,因為宣告會在 WCF 的各種點進行序列化。The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. 基本類型為可序列化。Primitive types are serializable.

    3. 選擇由 WCF 定義的許可權,或自訂許可權的唯一值。Choose a right that is defined by WCF or a unique value for a custom right.

      權限為唯一字串識別碼。A right is a unique string identifier. WCF 所定義的許可權會定義在 Rights 類別中。The rights that are defined by WCF are defined in the Rights class.

      自訂宣告設計者的責任在於確保用於權限的字串識別碼為獨一無二的。It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique.

      下列程式碼範例會使用 http://example.org/claims/simplecustomclaim 宣告類型,對名稱為 Driver's License 的資源建立自訂宣告,也會使用 PossessProperty 權限建立自訂宣告。The following code example creates a custom claim with a claim type of http://example.org/claims/simplecustomclaim, for a resource named Driver's License, and with the PossessProperty right.

    // Create claim with custom claim type and primitive resource
    Claim c1 = new Claim ( "http://example.org/claims/simplecustomclaim", "Driver's License", Rights.PossessProperty);
    
    ' Create claim with custom claim type and primitive resource
    Dim c1 As New Claim("http://example.org/claims/simplecustomclaim", "Driver's License", Rights.PossessProperty)
    

依據非基本資料型別建立自訂宣告To create a custom claim that is based on a non-primitive data type

  1. 將宣告類型、資源值和權限傳遞至 Claim(String, Object, String) 建構函式,即可建立自訂宣告。Create a custom claim by passing the claim type, resource value and right to the Claim(String, Object, String) constructor.

    1. 決定用於宣告類型的唯一值。Decide on a unique value for the claim type.

      宣告類型為唯一的字串識別碼。The claim type is a unique string identifier. 自訂宣告設計者的責任在於確保用於宣告類型的字串識別碼為獨一無二的。It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. 如需 WCF 所定義的宣告類型清單,請參閱 ClaimTypes 類別。For a list of claim types that are defined by WCF, see the ClaimTypes class.

    2. 選擇或定義資源的可序列化非基本類型。Choose or define a serializable non-primitive type for the resource.

      資源就是物件。A resource is an object. 資源的 CLR 類型必須是可序列化的,因為宣告會在 WCF 的各種點進行序列化。The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. 基本類型已為可序列化。Primitive types are already serializable.

      定義新類型時,請將 DataContractAttribute 套用至類別。When a new type is defined, apply the DataContractAttribute to the class. 也將 DataMemberAttribute 屬性套用至需要序列化以做為宣告一部分之新類型的所有成員。Also apply the DataMemberAttribute attribute to the all members of the new type that need to be serialized as part of the claim.

      下列程式碼範例會定義名稱為 MyResourceType 的自訂資源類型。The following code example defines a custom resource type named MyResourceType.

      [DataContract(Name="MyResource", Namespace="http://example.org/resources")]
      public sealed class MyResourceType
      {
        // private members
        private string text;
        private int number;
      
        // Constructors
        public MyResourceType()
        {
        }
      
        public MyResourceType(string text, int number )
        {
          this.text = text;
          this.number = number;
        }
      
        // Public properties
        [DataMember]
        public string Text { get { return this.text; }  set { this.text = value; } }
        [DataMember]
        public int Number { get { return this.number; } set { this.number = value; } }
      }
      
      <DataContract(Name:="MyResource", [Namespace]:="http://example.org/resources")> _
      NotInheritable Public Class MyResourceType
          ' private members
          Private text_value As String
          Private number_value As Integer
      
      
          ' Constructors
          Public Sub New()
      
          End Sub
      
      
          Public Sub New(ByVal text As String, ByVal number As Integer)
              Me.text_value = text
              Me.number = number
      
          End Sub
      
          ' Public properties
      
          <DataMember()> _
          Public Property Text() As String
              Get
                  Return Me.text_value
              End Get
              Set
                  Me.text_value = value
              End Set
          End Property
      
          <DataMember()> _
          Public Property Number() As Integer
              Get
                  Return Me.number_value
              End Get
              Set
                  Me.number_value = value
              End Set
          End Property
      End Class
      
    3. 選擇由 WCF 定義的許可權,或自訂許可權的唯一值。Choose a right that is defined by WCF or a unique value for a custom right.

      權限為唯一字串識別碼。A right is a unique string identifier. WCF 所定義的許可權會定義在 Rights 類別中。The rights that are defined by WCF are defined in the Rights class.

      自訂宣告設計者的責任在於確保用於權限的字串識別碼為獨一無二的。It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique.

      下列程式碼範例會使用 http://example.org/claims/complexcustomclaim 的宣告類型、MyResourceType 的自訂資源類型和 PossessProperty 權限,建立自訂宣告。The following code example creates a custom claim with a claim type of http://example.org/claims/complexcustomclaim, a custom resource type of MyResourceType, and with the PossessProperty right.

      // Create claim with custom claim type and structured resource type
      Claim c2 = new Claim ( "http://example.org/claims/complexcustomclaim", new MyResourceType ( "Martin", 38 ), Rights.PossessProperty);
      
      ' Create claim with custom claim type and structured resource type
      Dim c2 As New Claim("http://example.org/claims/complexcustomclaim", New MyResourceType("Martin", 38), Rights.PossessProperty)
      

範例Example

下列程式碼範例會示範如何使用基本資源類型和非基本資源類型建立自訂宣告。The following code example demonstrates how to create a custom claim with a primitive resource type and a custom claim with a non-primitive resource type.

using System;
using System.IdentityModel.Claims;
using System.Runtime.Serialization;
using System.Security.Permissions;
[assembly: SecurityPermission(
   SecurityAction.RequestMinimum, Execution = true)]
namespace Samples
{
  [DataContract(Name="MyResource", Namespace="http://example.org/resources")]
  public sealed class MyResourceType
  {
    // private members
    private string text;
    private int number;

    // Constructors
    public MyResourceType()
    {
    }

    public MyResourceType(string text, int number )
    {
      this.text = text;
      this.number = number;
    }

    // Public properties
    [DataMember]
    public string Text { get { return this.text; }  set { this.text = value; } }
    [DataMember]
    public int Number { get { return this.number; } set { this.number = value; } }
  }

  class Program
  {
    public static void Main()
    {
      // Create claim with custom claim type and primitive resource
      Claim c1 = new Claim ( "http://example.org/claims/simplecustomclaim", "Driver's License", Rights.PossessProperty);
      // Create claim with custom claim type and structured resource type
      Claim c2 = new Claim ( "http://example.org/claims/complexcustomclaim", new MyResourceType ( "Martin", 38 ), Rights.PossessProperty);

      // Do something with claims
    }
  }
}
Imports System.IdentityModel.Claims
Imports System.Runtime.Serialization
Imports System.Security.Permissions


<assembly: SecurityPermission(SecurityAction.RequestMinimum, Execution:=True)>

<DataContract(Name:="MyResource", [Namespace]:="http://example.org/resources")> _
NotInheritable Public Class MyResourceType
    ' private members
    Private text_value As String
    Private number_value As Integer


    ' Constructors
    Public Sub New()

    End Sub


    Public Sub New(ByVal text As String, ByVal number As Integer)
        Me.text_value = text
        Me.number = number

    End Sub

    ' Public properties

    <DataMember()> _
    Public Property Text() As String
        Get
            Return Me.text_value
        End Get
        Set
            Me.text_value = value
        End Set
    End Property

    <DataMember()> _
    Public Property Number() As Integer
        Get
            Return Me.number_value
        End Get
        Set
            Me.number_value = value
        End Set
    End Property
End Class

Class Program

    Public Shared Sub Main()
        ' Create claim with custom claim type and primitive resource
        Dim c1 As New Claim("http://example.org/claims/simplecustomclaim", "Driver's License", Rights.PossessProperty)
        ' Create claim with custom claim type and structured resource type
        Dim c2 As New Claim("http://example.org/claims/complexcustomclaim", New MyResourceType("Martin", 38), Rights.PossessProperty)
    End Sub
End Class
' Do something with claims

另請參閱See also