Custom profile redirections.xml

  • Article

Custom profile redirections are configured using an XML file (redirections.xml) located within the user's profile container. FSLogix doesn't create the redirections.xml file. The redirections.xml file is copied to the user's profile container from a source location. In most cases, the source location is a remote file share where the users have access to copy from and into their profile container. This document provides details on the redirection.xml file and how best to implement it for your specific use case.

When to use redirections.xml

Data in the user's profile isn't designed to be removed or excluded. Unless you have intimate knowledge of the data in the profile or the application, don't exclude it from the container.

Include and Exclude files and folders within a Profile container

To include / exclude files and / or folders within a users profile container, you need to create a file called redirections.xml. This file defines what to copy or exclude to / from a user's profile container. The XML file is processed during a users sign in and sign out of a virtual machine. Any changes made to the XML file while the user is signed into the virtual machine, doesn't take effect until they sign out and sign-in.

Removing or renaming the XML file at the source location doesn't remove or rename it for the users. If it's necessary to remove the custom redirections, clear out the XML file contents and save it to the source location. At the next sign-in, the updated file will be copied to the user's profile container.

Note

redirections.xml is only applicable when used with profile containers and has no effect when using ODFC containers.

Locations for redirections.xml

The XML file has two (2) locations. The source location, typically a remote file share, and the location in the user's profile container.

Source File Location

The XML file can be centrally located for easy distribution. The RedirXMLSourceFolder setting specifies a location where the client checks at sign in to see if there's a redirections.xml file. If one is found and it's different than the existing one, it's copied to the user's profile container. Then the contents are processed.

When stored in a central location (for example, root or subdirectory where user profile containers are stored), be sure users only have read permissions to the XML file.

Note

Only specify the path to the redirections.xml file, don't specify the file name.

User's Profile Location

The redirections.xml file resides in the following location when copied from the source location:

  • %userprofile%\AppData\Local\FSLogix\redirections.xml (inside the user's profile container)

Important

If any entry or entries in the redirections.xml are removed, the contents or folders remain in the VHD(x). Anything added in the redirections.xml is put in the local_%username% folder, but what already exists in the VHD(x) is not removed from the VHD(x).

XML File Contents

The redirections.xml file is composed of the XML declaration, three (3) elements and two (2) attributes. The XML declaration is standard and shouldn't be changed.

Elements and Attributes

  • FrxProfileFolderRedirection: This is the first element in the XML file and should be used only once.

    • ExcludeCommonFolders: This attribute defines which (if any) well known folders should be redirected out of the user's profile container. This attribute takes a bitmask value that tells FSLogix which combination of folders to exclude. Add up the values for all the folders to be excluded. For example, a value of 7 excludes the Contacts, Desktop, and Documents folders.

      • 1: Contacts folder
      • 2: Desktop folder
      • 4: Documents folder
      • 8: Downloads folder
      • 16: Links folder
      • 32: Music folders
      • 64: Pictures and Videos folders
      • 128: Folders involved in Low Integrity Level processes like AppData\LocalLow

    • Excludes: This element is used for a collection of nested Exclude elements.

      • Exclude: This element describes a single location to exclude from the user's container. The path used in these elements must exist in the user's profile path (%userprofile%). The path must NOT include the C:\Users\%username% part of the path.
        • Copy: This attribute defines how FSLogix handles the files and folders during the redirection. The attribute can be omitted from the element that is the same as using a value of 0.
          • 0: Creates an empty folder in the local_%username% directory. No files are copied during the operation. Copy 0 is the most common value used to decrease contents of a user's profile. Any data that is already in the container at the location isn't removed. Only future data is created in the local_%username% folder during the user’s session and removed at sign out.
          • 1: Creates the folder in the local_%username% directory AND copies the files FROM the specified location. Data in the container is copied to the local_%username% folder and any new data is also written to that path. At user sign out the local_%username% is removed and any new data is lost. Nth sign ins always copies data from the container to the local_%username% folder.
          • 2: Creates the folder in the local_%username% directory AND copies the files TO the specified location. A new (empty) folder is created in local_%username%. During the user's session, data is written to that path. At sign out, the data is copied into the container. Don't use this value unless directed by a Microsoft support engineer.
          • 3: Creates the folder in the local_%username% directory AND copies the files FROM and TO the specified location. This value combines the effects from 1 and 2. Existing data is copied out of the container and into the local_%username% folder. New data is written to the local_%username% path and at sign out, all data is copied back into the container.

    • Includes: This element is used for a collection of nested Include elements.

      • Include: This element is used to ensure a subdirectory of an exclude path is kept in the container. The COPY value isn't used in these elements. The path used in these elements must exist in the user's profile path (%userprofile%). The path must NOT include the C:\Users\%username% part of the path.

      Note

      • The folder or data must exist in the profile to be included back into the container. For example, new profiles using FSLogix with an include statement may not have all the folder structures created for a specific path because the user has never used the application within the context of their FSLogix profile container.
      • The parent folder of an included folder path MUST exist in the container for the include to work correctly.
      • The XML file will accept any number of Include and Exclude elements.

Example redirections.xml

Important

This example shows how the elements can be used. Follow the Create and implement redirections.xml tutorial for a real-world XML implementation. Exclues and includes can have unexpected consequences and must be created with care.

  1. Exclude the well-known folders (Contacts, Links, and Music)
  2. Exclude the Contoso Sales App, copying any data from the container to the local_%username% folder and back into the container at sign out. The exclude statement with copy moves the I/O of the data to the local disk instead of the container1.
  3. Exclude the Microsoft Edge folder with no copy operation (all data is removed at sign out).
  4. Include back the User Data folder inside the excluded Microsoft Edge folder.

1 I/O is still required to copy the data.

<?xml version="1.0"  encoding="UTF-8"?>
<FrxProfileFolderRedirection ExcludeCommonFolders="49">
<Excludes>
<Exclude Copy="3">AppData\Roaming\Contoso\ContosoSalesApp</Exclude>
<Exclude Copy="0">AppData\Local\Microsoft\Edge</Exclude>
</Excludes>
<Includes>
<Include>AppData\Local\Microsoft\Edge\User Data</Include>
</Includes>
</FrxProfileFolderRedirection>

Note

  • On Windows 8 and later, folders involved in Low Integrity Level processes are ALWAYS redirected to the local_%username% directory.
  • If the same folder is specified in both Exclude and Include elements, the Exclude will take precedence.
  • To list the redirections put in place by FSLogix, use the frx command-line utility.

Next steps

redirections.xml FAQ