Export (0) Print
Expand All

How to Configure a File Send Port

You can set File send port adapter variables either programmatically or by using the BizTalk Server Administration console.

How to Configure the Send Port Programmatically

The File adapter stores its configuration information in the SSO database. Configuration information is stored in a custom XML property bag. The File send handler property schema, bts_file_properties.xsd, defines the File adapter-specific properties. You use these properties to configure the File send ports, as well as for passing adapter-specific information within the server.

You can configure the send ports programmatically by using the BizTalk Explorer object model.The BizTalk Explorer object model exposes the ITransportInfo adapter configuration interface for File send ports, which contains the TransportTypeData read/write property. This property accepts the File send handler configuration property bag as a name/value pair XML string.

Setting the TransportTypeData property of the ITransportInfo interface is not required. If it is not set, the default values for the File send handler configuration are used.

The following table lists the configuration properties you can set programmatically in the BizTalk Explorer object model for the File send handler location.

 

Property name Type Description

CopyMode

Long

Define the copy mode to use when writing a message to a file. Valid values are:

Append (0). The File send handler opens a file if it exists and appends a message to the end of the file. If the file does not exist, the File send handler creates a new file.

Create new (1). If the file does not exist, the File send handler creates a new file and writes to it. If the file already exists, the File send handler reports an error and then follows common adapter retry logic for send ports. This is a default copy mode for the File send handler.

Overwrite (2). The File send handler opens a file if it exists and overwrites its content. If the file does not exist, the File send handler creates a new file.

AllowCacheOnWrite

Boolean

Defines whether the File adapter uses file system caching when writing messages to a file.

Valid values are:

True (-1) The File adapter uses file system caching when writing the output file.

False (0) The File send handler does not use file system caching when writing the output file.

Use temporary file while writing

Boolean

Defines whether to write the output file to a temporary file first and then rename the file once the write operation has completed. If this option is enabled then the temporary file will be created with the extension BTS-WIP.

Valid values are:

True (-1) The File adapter creates a temporary file when writing to the target folder.

False (0) The File adapter does not create a temporary file when writing to the target folder.

noteNote
This option is only available when the CopyMode property is set to a value of Create new (1).

If any of the configuration properties do not have a value on the message context, the File send handler uses its default value.

You can set configuration properties programmatically on a message context. You can set these properties in an orchestration or in a custom pipeline component. The following rules apply when using these properties:

  • If the configuration property is set in an orchestration or in a custom pipeline component in a receive pipeline, then:

    • If a message is sent to a static send port, the property value will be overwritten with the value configured for that send port.

    • If a message is sent to a dynamic send port, the property value will not be overwritten.

  • If a configuration property is set in a custom pipeline component in a send pipeline, then:

    • The value will not be overwritten regardless of whether the message is sent to a static or dynamic send port.

The following code shows the format of the XML string you can use to set the properties:

<CustomProps>
   <CopyMode vt="19">0</CopyMode>
   <AllowCacheOnWrite vt="11">-1</AllowCacheOnWrite>
   <UseTempFileOnWrite vt="11">-1</UseTempFileOnWrite>
</CustomProps>

Permissions required by a File adapter send handler host instance

Adapter handlers run under the security context of an instance of the host specified for the adapter handler in the BizTalk Administration console. The security context for a given instance of a host is determined by the Logon parameter of the <Host name> - Host Instance Properties dialog box in the BizTalk Administration console. The account specified by the Logon parameter of the <Host name> - Host Instance Properties dialog box must have the following permissions to any folders or shares that the File send adapter is writing to:

At the file level:

  • Traverse Folder / Execute File

  • List Folder / Read Data

  • Read Attributes

  • Read Extended Attributes

  • Create Files / Write Data

  • Create Folders/Append Data

  • Delete Subfolders and Files

  • Read Permissions

At the share level (if writing to a share):

  • Change

For more information about BizTalk hosts, see Hosts. For more information about BizTalk host instances, see Host Instances.

How to Set the File Adapter Configuration Properties for a Dynamic Send Port

A dynamic send port does not provide any transport configuration options in BizTalk Server Administration console because it is expected that these properties will be provided with the context properties associated with the message. These properties can be set in a custom pipeline or in an orchestration. To set message configuration properties in an orchestration you can do the following:

  • Add a Construct Message shape to your orchestration.

  • Configure the Construct Message shape to construct a new message. (for example Message_2)

  • Add a Message Assignment shape to the Construct Message shape.

  • Add code to the Message Assignment shape to initialize the message that you constructed and to set the appropriate configuration properties for the message. The following code initializes a message named Message_2 that was constructed with a Construct Message shape and then sets two configuration properties for the message. In this scenario, Message_1 was originally received by the orchestration:

    Message_2=Message_1;
    Message_2(FILE.CopyMode)= 0; //0=Append
    Message_2(FILE.AllowCacheOnWrite)= true;
    Message_2(FILE.UseTempFileOnWrite)= true;
    

How to Configure the Send Port with the BizTalk Server Administration Console

To configure the send port by using the BizTalk Server Administration console, use the following procedure.

To configure variables for a File send port

  1. In the BizTalk Server Administration console, create a new send port or double-click an existing send port to modify it. For more information, see How to Create a Send Port. Configure all of the send port options and specify FILE for the Type option in the Transport section of the General tab.

  2. On the General tab, in the Transport section, click the Configure button next to Type.

  3. In the File Transport Properties dialog box, on the General tab do the following:

     

    Use this To do this

    Destination Location

    Specify the path to the location on the file system or public share to write the output messages. You can enter the path directly in the Destination Location text box or select it from the file system by navigating to the folder with the Browse button. When browsing for the folder in the Browse For Folder dialog box you can also create a new folder by clicking Make New Folder.

    Type: String

    noteNote
    The URI for a send port or receive location cannot exceed 256 characters.

    File name

    Specify the name of the file where the File send handler writes the message.

    For information about restrictions on this property, see Restrictions on the File Mask and File Name Properties.

    For information about using macros in the file name, see Restrictions on Using Macros in File Names.

    Copy mode

    Define the copy mode to use when writing a message to a file. Valid values are:

    Append. The File send handler opens a file if it exists and appends a message to the end of the file. If the file does not exist, the File send handler creates a new file.

    Overwrite. The File send handler opens a file if it exists and overwrites its content. If the file does not exist, the File send handler creates a new file.

    Create new. If a file does not exist, the File send handler creates a new file and writes to it. If the file already exists, the File send handler reports an error and then follows common adapter retry logic for send ports. This is a default copy mode for the File send handler.

    Allow Cache on write

    Define whether to use file system caching when writing a message to a file.

    Valid options are:

    False Do not use the file system cache.

    True Use the file system cache.

    Default Value: False

    ImportantImportant
    Setting this property to True can increase the performance of the File adapter at the risk of potential data loss when there is a loss of power and not all data is written to disk.

    Use temporary file while writing

    Define whether to write the output file to a temporary file first and then rename the file once the write operation has completed. If this option is enabled then the temporary file will be created with the extension BTS-WIP.

    Valid options are

    True The File adapter creates a temporary file when writing to the target folder.

    False The File adapter does not create a temporary file when writing to the target folder.

    Default Value: False

    noteNote
    This option is only available when the CopyMode property is set to a value of Create new

  4. On the Authentication tab, in the File Transport Properties dialog box, do the following:

     

    Use this To do this

    Use these credentials when host does not have access to network share

    Specify to use alternative credentials when the host instance for the File adapter does not have the necessary rights to a network share. This option is only valid when accessing a network share.

    Default Value: False

    Type: Boolean

    User name

    Specify the user name that has access to the network share.

    Type: String

    Password

    Specify the password for the account that has access to the network share.

    Type: String

  5. Click OK and OK again to save settings.

See Also

© 2010 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft