Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

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:

  1. 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.
  2. 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.

Page Contents


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

To resolve Nuget dependencies, the plugin requires a .nuget directory within your Solution. Before you start installation, make sure that this directory exists.

 

You should see the following changes to your Solution:

  • A new custom project linked to the Artifactory plugin. 
  • .artifactory folder is added to your Solution. Make sure this directory is committed to source control.
  • Under the .artifactory folder, an Artifactory.build file is created. This is the main plugin configuration file.
  • Two .targets files 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.csproj and .nuget\NuGet.targets files 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 .artifactory folder 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

 


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.

MSBuild-Integrated Package Restore approach

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.Config file is ignored by the plugin.
  • Modifying the .nuget/NuGet.targets file can cause unexpected behavior in the resolution process. We strongly recommend that you do not modify these files manually.   
  • The .nuget folder 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.

 Overriding 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:

  1. Publishes the specified published artifacts to the selected target repository and applies the proper path mappings.
  2. 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 Propertiesand 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

 Click here to expand...
2.2.0 (10 Mar 2016)
  1. Support for TFS 2015
2.1.0 (18 Aug 2015)
  1. Support for Visual Studio 2015
  2. Bug fix MSBAI-7
2.0.0 (30 Apr 2015)
  1. Artifactory plugin as a Visual Studio Extension, and used as a "Project template" in the solution.
  2. Supporting Black Duck Code Center as part of the build process.
1.0.0 (30 Sep 2014)
  1. First release version.

 

 

 

 

 

  • No labels