Установите пользовательское свойство в текстовом редакторе

В этом разделе показано, как использовать классы в пакете SDK Open XML для Office для программного задания пользовательского свойства в текстовом документе. Он содержит пример SetCustomProperty метода для иллюстрации этой задачи.

Пример кода также включает в себя перечисление, которое определяет возможные типы настраиваемых свойств. При вызове SetCustomProperty метода необходимо указать одно из этих значений.

C#

enum PropertyTypes : int
{
    YesNo,
    Text,
    DateTime,
    NumberInteger,
    NumberDouble
}

Visual Basic

Enum PropertyTypes As Integer
    YesNo
    Text
    [DateTime]
    NumberInteger
    NumberDouble
End Enum

Формат хранения настраиваемых свойств

Важно понимать, как пользовательские свойства хранятся в текстовом документе. Чтобы узнать, как они хранятся, можно использовать средство повышения производительности для Microsoft Office, показанное на рис. 1. Это средство позволяет открыть документ и просмотреть его части и иерархию частей. На рисунке 1 показан тестовый документ после выполнения кода в разделе Вызов метода SetCustomProperty этой статьи. Средство отображает в правой области XML для части и отраженный код C#, который можно использовать для создания содержимого части.

Рис. 1. Средство повышения производительности пакета SDK Open XML для Microsoft Office

Соответствующий XML-код также извлечен и показан ниже для удобства.

    <op:Properties xmlns:vt="https://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes" xmlns:op="https://schemas.openxmlformats.org/officeDocument/2006/custom-properties">
      <op:property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="2" name="Manager">
        <vt:lpwstr>Mary</vt:lpwstr>
      </op:property>
      <op:property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="3" name="ReviewDate">
        <vt:filetime>2010-12-21T00:00:00Z</vt:filetime>
      </op:property>
    </op:Properties>

Если посмотреть на XML-содержимое, можно заметить следующее:

• Каждое свойство в XML-содержимом состоит из XML-элемента, включающего имя и значение свойства.
• Для каждого свойства XML-содержимое включает fmtid атрибут, для которого всегда задано одно и то же строковое значение: {D5CDD505-2E9C-101B-9397-08002B2CF9AE}.
• Каждое свойство в XML-содержимом pid содержит атрибут, который должен содержать целое число, начинающееся с 2 для первого свойства и приращение для каждого последующего свойства.
• Каждое свойство отслеживает свой тип (на рисунке vt:lpwstr имена элементов и vt:filetime определяют типы для каждого свойства).

Приведенный здесь пример метода содержит код, необходимый для создания или изменения пользовательского свойства документа в документе Microsoft Word. Полный листинг кода для этого метода приведен в разделе Пример кода.

Метод SetCustomProperty

Используйте метод , SetCustomProperty чтобы задать пользовательское свойство в текстовом документе. Метод SetCustomProperty принимает четыре параметра:

• Имя изменяемого документа (строковое значение).

• Имя изменяемого (или добавляемого) свойства (строковое значение).

• Значение свойства (объект).

• Тип свойства (одно из значений в перечислении PropertyTypes ).

C#

static string SetCustomProperty(
    string fileName,
    string propertyName,
    object propertyValue,
    PropertyTypes propertyType)

Visual Basic

Function SetCustomProperty(fileName As String, propertyName As String, propertyValue As Object, propertyType As PropertyTypes) As String

Вызов метода SetCustomProperty

Метод SetCustomProperty позволяет задать пользовательское свойство и возвращает текущее значение свойства, если оно существует. Чтобы вызвать пример метода, передайте имя файла, имя свойства, значение свойства и параметры типа свойства. Следующий код показывает пример использования:

C#

string fileName = args[0];

Console.WriteLine(string.Join("Manager = ", SetCustomProperty(fileName, "Manager", "Pedro", PropertyTypes.Text)));

Console.WriteLine(string.Join("Manager = ", SetCustomProperty(fileName, "Manager", "Bonnie", PropertyTypes.Text)));

Console.WriteLine(string.Join("ReviewDate = ", SetCustomProperty(fileName, "ReviewDate", DateTime.Parse("01/26/2024"), PropertyTypes.DateTime)));

Visual Basic

Sub Main(args As String())
    Dim fileName As String = args(0)

    Console.WriteLine(String.Join("Manager = ", SetCustomProperty(fileName, "Manager", "Pedro", PropertyTypes.Text)))

    Console.WriteLine(String.Join("Manager = ", SetCustomProperty(fileName, "Manager", "Shweta", PropertyTypes.Text)))

    Console.WriteLine(String.Join("ReviewDate = ", SetCustomProperty(fileName, "ReviewDate", DateTime.Parse("01/26/2024"), PropertyTypes.DateTime)))
End Sub

После выполнения этого кода используйте следующую процедуру для просмотра настраиваемых свойств в приложении Word.

1. Откройте файл .docx в Word.
2. На вкладке Файл выберите команду Сведения.
3. Щелкните Свойства.
4. Выберите команду Дополнительные свойства.

Настраиваемые свойства будут отображены в появившемся диалоговом окне, как показано на рис. 2.

Рис. 2. Пользовательские свойства в диалоговом окне "Дополнительные свойства"

Принципы работы кода

Метод SetCustomProperty начинается с настройки некоторых внутренних переменных. Затем он проверяет сведения о свойстве и создает новый CustomDocumentProperty объект на основе указанных параметров. Код также содержит переменную с именем propSet, указывающую, успешно ли создан новый объект свойства. Этот код проверяет тип значения свойства, а затем преобразует входные данные в правильный тип, задавая соответствующее CustomDocumentProperty свойство объекта .

Примечание.

Тип CustomDocumentProperty работает так же, как тип VBA Variant. В нем имеются отдельные заполнители, используемые в качестве свойств для различных типов данных, которые он может содержать.

C#

string? returnValue = string.Empty;

var newProp = new CustomDocumentProperty();
bool propSet = false;


string? propertyValueString = propertyValue.ToString() ?? throw new System.ArgumentNullException("propertyValue can't be converted to a string.");

// Calculate the correct type.
switch (propertyType)
{
    case PropertyTypes.DateTime:

        // Be sure you were passed a real date, 
        // and if so, format in the correct way. 
        // The date/time value passed in should 
        // represent a UTC date/time.
        if ((propertyValue) is DateTime)
        {
            newProp.VTFileTime =
                new VTFileTime(string.Format("{0:s}Z",
                    Convert.ToDateTime(propertyValue)));
            propSet = true;
        }

        break;

    case PropertyTypes.NumberInteger:
        if ((propertyValue) is int)
        {
            newProp.VTInt32 = new VTInt32(propertyValueString);
            propSet = true;
        }

        break;

    case PropertyTypes.NumberDouble:
        if (propertyValue is double)
        {
            newProp.VTFloat = new VTFloat(propertyValueString);
            propSet = true;
        }

        break;

    case PropertyTypes.Text:
        newProp.VTLPWSTR = new VTLPWSTR(propertyValueString);
        propSet = true;

        break;

    case PropertyTypes.YesNo:
        if (propertyValue is bool)
        {
            // Must be lowercase.
            newProp.VTBool = new VTBool(
              Convert.ToBoolean(propertyValue).ToString().ToLower());
            propSet = true;
        }
        break;
}

if (!propSet)
{
    // If the code was not able to convert the 
    // property to a valid value, throw an exception.
    throw new InvalidDataException("propertyValue");
}

Visual Basic

Dim returnValue As String = String.Empty

Dim newProp As New CustomDocumentProperty()
Dim propSet As Boolean = False

Dim propertyValueString As String = propertyValue.ToString()
If propertyValueString Is Nothing Then
    Throw New ArgumentNullException("propertyValue can't be converted to a string.")
End If

' Calculate the correct type.
Select Case propertyType
    Case PropertyTypes.DateTime
        ' Be sure you were passed a real date, 
        ' and if so, format in the correct way. 
        ' The date/time value passed in should 
        ' represent a UTC date/time.
        If TypeOf propertyValue Is DateTime Then
            newProp.VTFileTime = New VTFileTime(String.Format("{0:s}Z", Convert.ToDateTime(propertyValue)))
            propSet = True
        End If

    Case PropertyTypes.NumberInteger
        If TypeOf propertyValue Is Integer Then
            newProp.VTInt32 = New VTInt32(propertyValueString)
            propSet = True
        End If

    Case PropertyTypes.NumberDouble
        If TypeOf propertyValue Is Double Then
            newProp.VTFloat = New VTFloat(propertyValueString)
            propSet = True
        End If

    Case PropertyTypes.Text
        newProp.VTLPWSTR = New VTLPWSTR(propertyValueString)
        propSet = True

    Case PropertyTypes.YesNo
        If TypeOf propertyValue Is Boolean Then
            ' Must be lowercase.
            newProp.VTBool = New VTBool(Convert.ToBoolean(propertyValue).ToString().ToLower())
            propSet = True
        End If
End Select

If Not propSet Then
    ' If the code was not able to convert the 
    ' property to a valid value, throw an exception.
    Throw New InvalidDataException("propertyValue")
End If

На этом этапе, если код не создал исключение, можно предположить, что свойство допустимо, и код задает FormatId свойства и Name нового настраиваемого свойства.

C#

// Now that you have handled the parameters, start
// working on the document.
newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}";
newProp.Name = propertyName;

Visual Basic

' Now that you have handled the parameters, start
' working on the document.
newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
newProp.Name = propertyName

Работа с документом

С учетом CustomDocumentProperty объекта код взаимодействует с документом, предоставленным в параметрах SetCustomProperty процедуры. Код начинается с открытия документа в режиме Open чтения и записи с помощью метода WordprocessingDocument класса . Код пытается получить ссылку на часть настраиваемых свойств файла с помощью CustomFilePropertiesPart свойства документа.

C#

using (var document = WordprocessingDocument.Open(fileName, true))
{
    var customProps = document.CustomFilePropertiesPart;

Visual Basic

Using document As WordprocessingDocument = WordprocessingDocument.Open(fileName, True)
    Dim customProps = document.CustomFilePropertiesPart

Если коду не удается найти часть, содержащую настраиваемые свойства, он создает новую часть и добавляет в нее новый набор свойств.

C#

if (customProps is null)
{
    // No custom properties? Add the part, and the
    // collection of properties now.
    customProps = document.AddCustomFilePropertiesPart();
    customProps.Properties = new Properties();
}

Visual Basic

If customProps Is Nothing Then
    ' No custom properties? Add the part, and the
    ' collection of properties now.
    customProps = document.AddCustomFilePropertiesPart()
    customProps.Properties = New Properties()
End If

Затем код извлекает ссылку Properties на свойство части настраиваемых свойств (то есть ссылку на сами свойства). Если бы перед кодом стояла задача создания новой части для настраиваемых свойств, то, как вы скорее всего знаете, есть гарантия, что эта ссылка не будет иметь значение null. Однако для существующих частей настраиваемых свойств возможно, хотя и весьма маловероятно, что Properties свойство будет иметь значение NULL. И если это так, код не сможет продолжить работу.

C#

var props = customProps.Properties;

if (props is not null)
{

Visual Basic

Dim props = customProps.Properties

If props IsNot Nothing Then

Если свойство уже существует, код получает его текущее значение, а затем удаляет свойство . Зачем удалять свойство? Если новый тип свойства соответствует существующему типу свойства, код может задать для свойства новое значение. С другой стороны, если новый тип не совпадает, код должен создать новый элемент, удалив старый (это имя элемента, определяющего его тип. Дополнительные сведения см. на рис. 1). Проще всегда удалять, а затем повторно создавать элемент. Код использует простой запрос LINQ для поиска первого соответствия имени свойства.

C#

var prop = props.FirstOrDefault(p => ((CustomDocumentProperty)p).Name!.Value == propertyName);

// Does the property exist? If so, get the return value, 
// and then delete the property.
if (prop is not null)
{
    returnValue = prop.InnerText;
    prop.Remove();
}

Visual Basic

Dim prop = props.FirstOrDefault(Function(p) CType(p, CustomDocumentProperty).Name.Value = propertyName)

' Does the property exist? If so, get the return value, 
' and then delete the property.
If prop IsNot Nothing Then
    returnValue = prop.InnerText
    prop.Remove()
End If

Теперь можно быть уверенным, что часть для настраиваемого свойства существует; что свойство с именем, совпадающим с новым свойством, не существует; и что могут уже существовать и другие настраиваемые свойства. Код выполняет следующие действия:

1. Добавляет новое свойство как дочерний объект в коллекцию свойств.

2. Циклически просматривает все существующие свойства и задает pid атрибуту увеличивающиеся значения, начиная с 2.

3. Сохраняет часть.

C#

// Append the new property, and 
// fix up all the property ID values. 
// The PropertyId value must start at 2.
props.AppendChild(newProp);
int pid = 2;
foreach (CustomDocumentProperty item in props)
{
    item.PropertyId = pid++;
}

Visual Basic

' Append the new property, and 
' fix up all the property ID values. 
' The PropertyId value must start at 2.
props.AppendChild(newProp)
Dim pid As Integer = 2
For Each item As CustomDocumentProperty In props
    item.PropertyId = pid
    pid += 1
Next

Наконец, код возвращает исходное сохраненное ранее значение свойства.

C#

return returnValue;

Visual Basic

Return returnValue

Пример кода

Ниже приведен полный SetCustomProperty пример кода на C# и Visual Basic.

C#

static string SetCustomProperty(
    string fileName,
    string propertyName,
    object propertyValue,
    PropertyTypes propertyType)
{
    // Given a document name, a property name/value, and the property type, 
    // add a custom property to a document. The method returns the original
    // value, if it existed.


    string? returnValue = string.Empty;

    var newProp = new CustomDocumentProperty();
    bool propSet = false;


    string? propertyValueString = propertyValue.ToString() ?? throw new System.ArgumentNullException("propertyValue can't be converted to a string.");

    // Calculate the correct type.
    switch (propertyType)
    {
        case PropertyTypes.DateTime:

            // Be sure you were passed a real date, 
            // and if so, format in the correct way. 
            // The date/time value passed in should 
            // represent a UTC date/time.
            if ((propertyValue) is DateTime)
            {
                newProp.VTFileTime =
                    new VTFileTime(string.Format("{0:s}Z",
                        Convert.ToDateTime(propertyValue)));
                propSet = true;
            }

            break;

        case PropertyTypes.NumberInteger:
            if ((propertyValue) is int)
            {
                newProp.VTInt32 = new VTInt32(propertyValueString);
                propSet = true;
            }

            break;

        case PropertyTypes.NumberDouble:
            if (propertyValue is double)
            {
                newProp.VTFloat = new VTFloat(propertyValueString);
                propSet = true;
            }

            break;

        case PropertyTypes.Text:
            newProp.VTLPWSTR = new VTLPWSTR(propertyValueString);
            propSet = true;

            break;

        case PropertyTypes.YesNo:
            if (propertyValue is bool)
            {
                // Must be lowercase.
                newProp.VTBool = new VTBool(
                  Convert.ToBoolean(propertyValue).ToString().ToLower());
                propSet = true;
            }
            break;
    }

    if (!propSet)
    {
        // If the code was not able to convert the 
        // property to a valid value, throw an exception.
        throw new InvalidDataException("propertyValue");
    }

    // Now that you have handled the parameters, start
    // working on the document.
    newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}";
    newProp.Name = propertyName;

    using (var document = WordprocessingDocument.Open(fileName, true))
    {
        var customProps = document.CustomFilePropertiesPart;

        if (customProps is null)
        {
            // No custom properties? Add the part, and the
            // collection of properties now.
            customProps = document.AddCustomFilePropertiesPart();
            customProps.Properties = new Properties();
        }

        var props = customProps.Properties;

        if (props is not null)
        {

            // This will trigger an exception if the property's Name 
            // property is null, but if that happens, the property is damaged, 
            // and probably should raise an exception.

            var prop = props.FirstOrDefault(p => ((CustomDocumentProperty)p).Name!.Value == propertyName);

            // Does the property exist? If so, get the return value, 
            // and then delete the property.
            if (prop is not null)
            {
                returnValue = prop.InnerText;
                prop.Remove();
            }

            // Append the new property, and 
            // fix up all the property ID values. 
            // The PropertyId value must start at 2.
            props.AppendChild(newProp);
            int pid = 2;
            foreach (CustomDocumentProperty item in props)
            {
                item.PropertyId = pid++;
            }
        }
    }

    return returnValue;
}

Visual Basic

Function SetCustomProperty(fileName As String, propertyName As String, propertyValue As Object, propertyType As PropertyTypes) As String
    ' Given a document name, a property name/value, and the property type, 
    ' add a custom property to a document. The method returns the original
    ' value, if it existed.

    Dim returnValue As String = String.Empty

    Dim newProp As New CustomDocumentProperty()
    Dim propSet As Boolean = False

    Dim propertyValueString As String = propertyValue.ToString()
    If propertyValueString Is Nothing Then
        Throw New ArgumentNullException("propertyValue can't be converted to a string.")
    End If

    ' Calculate the correct type.
    Select Case propertyType
        Case PropertyTypes.DateTime
            ' Be sure you were passed a real date, 
            ' and if so, format in the correct way. 
            ' The date/time value passed in should 
            ' represent a UTC date/time.
            If TypeOf propertyValue Is DateTime Then
                newProp.VTFileTime = New VTFileTime(String.Format("{0:s}Z", Convert.ToDateTime(propertyValue)))
                propSet = True
            End If

        Case PropertyTypes.NumberInteger
            If TypeOf propertyValue Is Integer Then
                newProp.VTInt32 = New VTInt32(propertyValueString)
                propSet = True
            End If

        Case PropertyTypes.NumberDouble
            If TypeOf propertyValue Is Double Then
                newProp.VTFloat = New VTFloat(propertyValueString)
                propSet = True
            End If

        Case PropertyTypes.Text
            newProp.VTLPWSTR = New VTLPWSTR(propertyValueString)
            propSet = True

        Case PropertyTypes.YesNo
            If TypeOf propertyValue Is Boolean Then
                ' Must be lowercase.
                newProp.VTBool = New VTBool(Convert.ToBoolean(propertyValue).ToString().ToLower())
                propSet = True
            End If
    End Select

    If Not propSet Then
        ' If the code was not able to convert the 
        ' property to a valid value, throw an exception.
        Throw New InvalidDataException("propertyValue")
    End If

    ' Now that you have handled the parameters, start
    ' working on the document.
    newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
    newProp.Name = propertyName

    Using document As WordprocessingDocument = WordprocessingDocument.Open(fileName, True)
        Dim customProps = document.CustomFilePropertiesPart

        If customProps Is Nothing Then
            ' No custom properties? Add the part, and the
            ' collection of properties now.
            customProps = document.AddCustomFilePropertiesPart()
            customProps.Properties = New Properties()
        End If

        Dim props = customProps.Properties

        If props IsNot Nothing Then

            ' This will trigger an exception if the property's Name 
            ' property is null, but if that happens, the property is damaged, 
            ' and probably should raise an exception.

            Dim prop = props.FirstOrDefault(Function(p) CType(p, CustomDocumentProperty).Name.Value = propertyName)

            ' Does the property exist? If so, get the return value, 
            ' and then delete the property.
            If prop IsNot Nothing Then
                returnValue = prop.InnerText
                prop.Remove()
            End If

            ' Append the new property, and 
            ' fix up all the property ID values. 
            ' The PropertyId value must start at 2.
            props.AppendChild(newProp)
            Dim pid As Integer = 2
            For Each item As CustomDocumentProperty In props
                item.PropertyId = pid
                pid += 1
            Next
        End If
    End Using

    Return returnValue
End Function

См. также

• Справочник по библиотеке классов пакета SDK Open XML