7.9 KiB
| external help file | Module Name | online version | schema |
|---|---|---|---|
| NTFSSecurity.dll-Help.xml | NTFSSecurity | https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSSymbolicLink.md | 2.0.0 |
New-NTFSSymbolicLink
SYNOPSIS
Creates a symbolic link to an existing file or folder.
SYNTAX
New-NTFSSymbolicLink [-Path] <String> [-Target] <String> [-PassThru] [<CommonParameters>]
DESCRIPTION
The New-NTFSSymbolicLink cmdlet creates a symbolic link that redirects to another file or folder. -Path is the new link that the cmdlet creates, and -Target is the existing item that the link points to. Read the command as "create Path, which points to Target". Both parameters are required.
Before it creates the link, the cmdlet inspects the target and creates a file symbolic link when the target is a file and a directory symbolic link when the target is a folder, so you do not select the link type yourself. -Target must exist when the link is created, and -Path must not exist yet, so the cmdlet never overwrites an existing item.
Relative paths are resolved against the current location before the link is created, which means that the link always stores an absolute target path.
To create several links, pipe objects with the properties Path and Target to the cmdlet, one link per object. For a link that it can't create, the cmdlet writes a non-terminating error and continues with the next object.
By default the cmdlet produces no output. With -PassThru it returns an object for the new link: a file object for a link to a file, and a folder object for a link to a folder.
EXAMPLES
Example 1: Create a symbolic link to a file
PS C:\> New-NTFSSymbolicLink -Path C:\Data\Report-Current.txt -Target C:\Data\Archive\Report-2026.txt
This command creates the symbolic link Report-Current.txt, which redirects to the existing file Report-2026.txt. Because the target is a file, the cmdlet creates a file symbolic link.
Example 2: Create a symbolic link to a folder
PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026
This command creates the symbolic link C:\Data\Current, which redirects to the existing folder C:\Data\Archive\2026. Because the target is a folder, the cmdlet creates a directory symbolic link, and paths below C:\Data\Current resolve to the corresponding items in the target folder.
Example 3: Create a link and return it
PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 -PassThru
This command creates the link and returns an object for the new link, which you can use to confirm the result in a script.
Example 4: Verify that the link resolves
PS C:\> Test-Path2 -Path C:\Data\Current\Report.txt -PathType Leaf
This command tests a path that leads through the symbolic link. It returns $true when the link resolves and the file exists in the target folder.
Example 5: Create several links from a list
PS C:\> Import-Csv -Path C:\Data\Links.csv | New-NTFSSymbolicLink
This command creates one symbolic link for each row of Links.csv, which has the columns Path and Target. For a row whose link it can't create, the cmdlet writes an error and continues with the next row.
PARAMETERS
-PassThru
Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object for a link to a file and a folder object for a link to a folder.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Path
Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location.
Type: String
Parameter Sets: (All)
Aliases: FullName
Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-Target
Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 2
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
System.String
You can pass the path of the new link and the path of the target as strings.
System.Management.Automation.PSObject
You can pipe objects whose Path or FullName property names the new link and whose Target property names its target, such as the rows of a CSV file that Import-Csv reads.
OUTPUTS
Alphaleonis.Win32.Filesystem.FileInfo
With -PassThru, the cmdlet writes a file object for a new link to a file. Without -PassThru, the cmdlet writes nothing.
Alphaleonis.Win32.Filesystem.DirectoryInfo
With -PassThru, the cmdlet writes a folder object for a new link to a folder. Before 5.0.0, it wrote a file object for those links as well.
NOTES
Creating a symbolic link on Windows requires the "Create symbolic links" user right, SeCreateSymbolicLinkPrivilege, which is granted to the Administrators group by default. Without that right, Windows rejects the operation with error 1314, "A required privilege is not held by the client", so run the cmdlet from an elevated session or grant the right to the account. Windows Developer Mode doesn't change this: it lets accounts without that right create symbolic links only in programs that request it, such as mklink, and the cmdlet doesn't.
Unlike a hard link, a symbolic link is a separate file system entry that stores a path, so it can point to an item on another volume and the link and its target can be managed independently. The cmdlet still requires the target to exist at the moment the link is created. If the target is removed later, the link remains and stops resolving.
If -Path already exists, -Target is missing, or a path contains a character that Windows doesn't allow, such as |, the cmdlet writes a non-terminating CreateSymbolicLinkError with the category ResourceExists, ObjectNotFound, or InvalidArgument, leaves the file system unchanged, and continues with the next object from the pipeline. It checks -Path before -Target, and the error for an existing -Path or a missing -Target names that path. When Windows refuses the link, such as with error 1314 without the right to create symbolic links, the cmdlet writes a CreateSymbolicLinkError as well.
Deleting a symbolic link removes the link only and leaves the target untouched. Delete a directory symbolic link as a link rather than recursively, so that the content of the target folder is not affected.
Before 5.0.0-rc7, -Path and -Target were optional: without -Path, the cmdlet failed with an index error, and without -Target, it created a link to the current folder. It stopped with a terminating error for an existing -Path or a link that Windows refused, in Windows PowerShell also for a path with a character that Windows doesn't allow, and every object piped to it failed with GetDefaultValueFailed. It checked -Target before -Path, and its errors for an existing -Path and a missing -Target named no path.