> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/tools/deployer.md).

# Deployment Tool

Use dotnet-deploy to combine local and NuGet artifacts into a verifiable host run directory.

`dotnet-deploy` reads the `.deploy` file, performing file copying, NuGet package parsing, and explicit deletion. It solves the assembly problem of the runtime directory and is not responsible for business data migration, system service installation or ensuring that all DLL versions are automatically compatible.

## Installation and Version

{% code title="InstallDeployer.ps1" %}

```powershell
dotnet tool install -g Zongsoft.Tools.Deployer
dotnet tool list -g
```

{% endcode %}

Use `dotnet tool update -g Zongsoft.Tools.Deployer` when installed. The team’s release process should pin tool versions and record package versions to avoid different machines selecting different latest packages.

## Minimal Deployment

Execute in the project directory containing `.deploy` and specify the target run directory and framework parameters:

{% code title="DeployApplication.ps1" %}

```powershell
dotnet deploy .deploy --destination:./out --edition:Release --framework:net10.0 --platform:win --architecture:x64
```

{% endcode %}

{% code title=".deploy" %}

```ini
[plugins]
nuget:Zongsoft.Plugins/plugins/Main.plugin

[plugins zongsoft data]
nuget:Zongsoft.Data
```

{% endcode %}

This is just a plugin combination fragment. The target directory also needs the host’s runtime artifacts. See [Deploy Your First Plugin](/documentation/en/get-started/deploy-first-plugin.md) for the complete workflow. When specifying other files, replace `.deploy` with the corresponding files; you can also pass in multiple lists according to the application plan.

## File Selection and Overwriting

Sections represent target subdirectories, and entries specify local files, packages, or deletion actions. See [Deployment format reference](/documentation/en/references/deploy-files.md) for variables, conditions and path details.

The existing values of `--overwrite` are `alway`, `never`, and `newest`; `alway` is the actual spelling of the tool, do not change it to `always` by yourself. `newest` decides whether to overwrite based on its file policy, which does not mean selecting the highest version based on assembly version.

{% hint style="warning" %}
🚨 Deployment is a sequential file operation. Transitive dependencies of subsequent packages may overwrite previously copied DLLs or even become older versions; NuGet entries do not resolve versions across the entire deployment graph as a single unit. Check the final directory’s assembly versions and the first business call.
{% endhint %}

## NuGet and Ancillary Resources

When the path within the package is not specified, the package root `.deploy` is processed first, otherwise the `lib` asset that is most suitable for the target framework is selected. Manifests within framework packages may also copy `.plugin`, `.option`, `.mapping`, SQL, language libraries, or native resources.

Some dependency prefixes are ignored by default, including `System.`, `Microsoft.Extensions.`, `Zongsoft.`. Therefore, when relying on the host base library or other Zongsoft plugins, you need to check the host artifacts and explicit manifest combinations, and cannot just rely on transitive copying.

## Inspection and Acceptance

When the path contains a Windows drive letter, prevent it from being mistakenly recognized as a resolver, such as using `:D:/...`; when the framework assets are missing, check `framework` and the actual package directory; when the configuration does not appear, check the conditions and application variables.

Check the error output, target files and running results at the same time during acceptance. Currently some undefined resolver errors do not result in a non-zero exit code, and the deployment cannot be deemed successful based on the script exit code alone. Windows Automation also requires a valid console handle, and console errors should be checked in the actual terminal where the tool is running.

Source references: [deployer](https://github.com/Zongsoft/tools/tree/main/deployer), [Complete command description](https://github.com/Zongsoft/tools/blob/main/deployer/README.zh-Hans.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/tools/deployer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.