Overview
DEPRECATION NOTICE
From version 2017 of Visual Studio, the MSBuild Artifactory Plugin is no longer supported.
To enable the continued use of MSBuild with Artifactory, JFrog has developed an alternative solution which can be found in JFrog's GitHub repository where it is, also, fully documented.
The current MSBuild Artifactory Plugin is now deprecated and we recommend using the new solution with all versions of Visual Studio.
Artifactory brings Continuous Integration to MSBuild, TFS and Visual Studio through the MSBuild Artifactory Plugin. This allows you to capture information about deployed artifacts, resolve Nuget dependencies and environment data associated with MSBuild build runs, and deploy artifacts to Artifactory. In addition, the exhaustive build information captured by Artifactory enables fully traceable builds.
MSBuild Artifactory Plugin
The MSBuild Artifactory plugin is an open source project on GitHub which you can freely browse and fork.
Sample code
To get yourself started, here is an example of a solution with multiple projects that use the MSBuild Artifactory Plugin
The MSBuild Artifactory Plugin can be used whether you are running standalone builds or using a CI server. In either case, you should note the following points:
- Standalone Integration
The MSBuild Artifactory Plugin fully integrates with the MSBuild process, so it can run as part of a standard build.
The plugin uses a conventional MSBuild XML configuration file to influence different stages of the build process. - CI Server Integration
When running MSBuild builds in your continuous integration server, using the plugin is transparent since it is effectively an integral part of the MSBuild process. The only difference is that the plugin collects information from the CI server.
The MSBuild Artifactory Plugin fully supports TFS and collects exhaustive build information to enable fully traceable builds. Support for additional CI servers such as Jenkins, TeamCity and Bamboo is partial, and the build information collected when running with these tools is correspondingly partial.
Installation
The MSBuild Artifactory Plugin is installed as a "Project Template" using Visual Studio as follows:
- Under Tools, choose Extensions and Updates..., select the Visual Studio Gallery source under the Online section, and run a search for "Artifactory".
Select Artifactory Template Package extension found, and click Install.
- Once the installation is complete, select the Solution into which you want to install the plugin. right-click the solution node and select Add | New Project.... Select Artifactory and click OK.
Creating Artifactory project
You should see the following changes to your Solution:
- A new custom project linked to the Artifactory plugin.
- A
.artifactoryfolder is added to your Solution. Make sure this directory is committed to source control. - Under the
.artifactoryfolder, anArtifactory.buildfile is created. This is the main plugin configuration file. - Two
.targetsfiles are created. These are used internally by the plugin and should not be modified manually.
- New Nuget packages related to the plugin should have been installed into the Solution.
- The plugin also imports its own MSBuild configuration file to the
artifactory.csprojand.nuget\NuGet.targetsfiles in order to be added to the MSBuild process.
The last step will be to link your relevant projects to the Artifactory project via the added Project Reference. Only the linked projects will be monitor by the plugin.
Installing plugin dependencies
The following two dependencies: Nuget.core v2.8.2 and Microsoft.Web.Xdt v2.1.1 must also be installed together with the plugin.
If you are installing the plugin from an instance of Artifactory, you need to ensure that Artifactory has access to the plugin and its dependencies. For example, you might have a virtual repository that references a local repository containing the plugin, and a remote repository that references nuget.org. For more details on configuring Artifactory, please refer to NuGet Repositories.
Update
To update Artifactory extensions, execute the following steps:
- Under Tools, select Extensions and Updates..., and then, the "Visual Studio Gallery" source under the Updates section.
Select the Artifactory Template Package extension found, and click Update.
Existing Project (Optional Step)
If you already have an existing Artifactory project template in your solution, and you want to update it to the latest one, execute the following steps:
- Right-click on the Artifactory project and select Manage NuGet Packages...
- In the Manage NuGet Packages window, select a source (e.g. nuget.org) under the Updates section.
Select the Artifactory package found, and click Update.
Uninstalling
- Remove the
.artifactoryfolder and its contents from the solution. - Remove the custom Artifactory project from the solution.
Make sure to delete the items from the file system also.
Migration from the old plugin implementation
To migrate from the old plugin implementation, you need to uninstall it and then install the new implementation
- Follow the steps described in Uninstalling.
- Follow the steps described in Installation.
Configuration
General Information
The MSBuild Artifactory Plugin is configured in the Artifactory.build configuration file. The file is structured using MSBuild language conventions, so all the properties can be externally overridden using Reserved Properties or Environment Properties.
MSBuild can collect properties that were configured in the build scope, or in the Environment Variables. This ability can be helpful in different cases:
- You can dynamically override the plugin configuration according to the build context that it runs in.
- You can prevent sensitive information from being checked into source control.
For example, if the build runs under a build server such as TFS, all the Artifactory credentials can be defined by the server administrator, and will therefore, not be Checked in/Committed to source control.
For more information about MSBuild properties, please refer to the MSBuild Reference Documentation.
Configuration Instructions
For more details on configuration, please refer to the Artifactory.build configuration file.
Resolution
To resolve packages, the MSBuild Artifactory Plugin uses the
NuGet Package Restore feature with the
MSBuild-Integrated Package Restore approach. To support this, the project that installed the plugin must be a part of a solution with the .nuget folder. If the .nuget folder is absent, the plugin will not override the Package Restore in the solution.
Please note the following points:
- Even though the plugin is installed on a project level, it overrides the NuGet resolution on all the projects under the same solution.
- Manual configuration in the
.nuget/NuGet.Configfile is ignored by the plugin. - Modifying the
.nuget/NuGet.targetsfile can cause unexpected behavior in the resolution process. We strongly recommend that you do not modify these files manually. - The
.nugetfolder must be committed to source control.
Ensuring package resolution through Artifactory
In order to mitigate situations in which a network connection is not available, the NuGet client locally caches any artifacts downloaded from a remote repository in the NuGet Local Cache (under %AppData%\Local\NuGet\Cache). Subsequently, the NuGet client first checks the cache when trying to resolve packages. Therefore, artifacts downloaded from a remote repository in Artifactory or from the NuGet Gallery, typically get stored in this local cache and will be provided from the cache next time you try to reference them.
To ensure that the NuGet client resolves packages through Artifactory, you need to delete the NuGet Local Cache.
Deployment
In order to support a wide variety of project templates, solution structures and artifact types, the MSBuild Artifactory Plugin is designed to be very flexible and allows the user great freedom in configuring how to deploy packages.
- Using an Input Pattern, the user can specify the path to files that the plugin will collect for deployment. The path is relative to the project in which the plugin is installed, and to other projects referenced by it in the solution.
- Using an Output Pattern, the user can specify a deployment path in Artifactory that corresponds to the specified Input Pattern.
- The user can also specify Custom Properties that should annotate all the artifacts resulting from the specified Input Pattern.
Target repository layout
You may define a custom layout for your target repository, but it is up to you to specify the right Output Pattern to ensure that your artifacts are deployed to the right location within the repository. For more details, please refer to Local Repositories.
Checksum Deployment
To support Artifactory's "Once-And-Only-Once" Content Storage, the plugin efficiently deploys packages to Artifactory using Checksum Deployment. Before an artifact is actually deployed, the plugin passes its checksum to Artifactory.
If the package already exists then Artifactory does not accept a new copy, it just creates a new metadata entry in the database to indicate that another "copy" of the artifact exists in specified deployment path.
Project-specific Deployment
The Artifactory.build file under the .artifactory directory applies to all projects within the solution. However, you can override the deployment configuration for a specific project providing an Artifactory.build file within the project scope. For example, you could use this to specify the full path of an artifact that needs to be deployed. The plugin detects the project-specific Artifactory.build file and applies the deployment configuration to that project, overriding the general deployment configuration. The example below shows the "ArtifactoryDemo.DAL" project with its own Artifactory.build file to overide the general solution deployment configuration.
Environment Variables
You can enable the EnvironmentVariables tag so that MSBuild Artifactory Plugin uses all environment variables accessible by the build process and registers them in the build info. If running under a build server, the server's properties also used and registered. You may define IncludePatterns and ExcludePatterns to control which variables are included in the published build info.
Pattern wildcards
A pattern may contain the * and the ? wildcards. Include patterns are applied before exclude patterns.
Extensive build information may slow down deployment
Including all environment variables as part of the captured build information may result in very large build objects which in turn, may slow down deployment.
License Control
MSBuild Artifactory Plugin supports Artifactory Pro License Control. This feature is controlled by several tags in the Artifactory.build configuration file.
LicenseControl | Enables or disables the license control feature |
LicenseViolationRecipients | Specifies addresses of recipients that should receive license alerts by email |
AutomaticLicenseDiscovery | When set, Artifactory will analyze and tag the build's dependencies with license information upon deployment Resource intensive Automatic license discovery is a resource intensive operation which may slow down deployment. If you do not run automatic license discovery, you can still attach license information manually by running 'Auto-Find' from the build's Licenses tab in the Artifactory UI. For more details, please refer to Examining Build Licenses. |
IncludePublishedArtifacts | License checks are usually only run on the dependencies of the published package. If this flag is set, a license check is run on the deployed artifact itself (only valid for NuGet packages) |
ScopesForLicenseAnalysis | Lets you specify the scopes on which license analysis should be run. |
Black Duck Code Center Integration
If you are using Artifactory Pro and have an account with Black Duck Code Center, you can run the build through an automated, non-invasive, open source component approval process, and monitor for security vulnerabilities.
BlackDuckComplianceCheck | Enables or disables the license control feature |
CodeCenterApplicationName | The existing Black Duck Code Center application name |
CodeCenterApplicationVersion | The existing Black Duck Code Center application version |
LicenseViolationRecipients | Specifies addresses of recipients that should receive license alerts by email |
ScopesForLicenseAnalysis | Lets you specify the scopes on which license analysis should be run. |
IncludePublishedArtifacts | License checks are usually only run on the dependencies of the published package. If this flag is set, a license check is run on the deployed artifact itself (only valid for NuGet packages) |
AutoCreateMissingComponent | Auto create missing components in Black Duck Code Center application after the build is completed and deployed in Artifactory. |
AutoDiscardStaleComponent | Auto discard stale components in Black Duck Code Center application after the build is completed and deployed in Artifactory. |
Network Configuration
Deploying via Proxy
MSBuild Artifactory Plugin supports deployments via your network proxy. If the values in the ProxySettings tag of the Artifactory.build configuration file are not recognized by the plugin, it will fall back to using the http_proxy Environment Variables for proxy configuration using the format http://<username>:<password>@proxy.com.
You can bypass the proxy by setting the Bypass tag in the plugin configuration.
Resolution Proxy
Due to a technical issue in the Nuget Client, you cannot configure the NuGet client for resolution via a proxy through the plugin. For the Nuget client to resolve artifacts via a proxy, you need to configure the proxy settings in %APPDATA%\NuGet\NuGet.Config.
For more information on how to configure a Nuget proxy, please refer to NuGet Config Settings.
Running a build with MSBuild Artifactory Plugin
Once you have completed setting up the MSBuild Artifactory Plugin, you can run a project build. The plugin takes effect at the end of the build and does the following:
- Publishes the specified published artifacts to the selected target repository and applies the proper path mappings.
- Deploys the BuildInfo to Artifactory, providing full traceability of the build, with links back to the build in TFS.
The example below shows Visual Studio output of a build log (minimum verbosity log level: Normal) with some deployed artifacts. At the bottom there is a link to the Build Info report on Artifactory.
Team Foundation Server (TFS) Integration
MSBuild Artifactory Plugin brings CI Build Integration to TFS users allowing you to efficiently deploy your artifacts to Artifactory. In addition to the BuildInfo that the plugin already registers, all parameters associated with TFS are also recorded to facilitate fully traceable builds.
For more information about how build information is used in Artifactory, please refer to BuildInfo.
MSBuild Arguments in TFS
The MSBuild Artifactory Plugin configuration file supports MSBuild Reserved Properties or Environment Properties, and the best practice is to define these properties in the TFS build configuration. This lets you protect sensitive information and run the same build with different properties. Below is an example of properties configured in the TFS build definition.
Package Restore with Team Foundation Build
For Team Foundation Build 2013 on-premises, the default Build Process Templates already implement the NuGet Package Restore Workflow without any special configuration.
To avoid NuGet Package Restore from outside the plugin, you need to remove it from the workflow.
License
The MSBuild Artifactory plugin is available under the Apache v2 License.
Screencast
Changelog